@silverassist/agents-toolkit 2.0.0 → 2.2.0

package/README.md

@@ -11,18 +11,25 @@ Reusable AI agent prompts for development workflows — supports **GitHub Copilo
 - ✅ **Multi-Agent Support**: Works with GitHub Copilot, Claude Code, and Codex
 - ✅ **Multi-Stack Filtering**: Install only React or WordPress content with `--stack`
 - ✅ **Multi-Tracker Support**: Choose GitHub Issues or Jira workflows with `--tracker`
+- ✅ **Global Install**: Install once for all projects with `--global`
 - ✅ **Modular Partials**: Reusable prompt fragments
 - ✅ **Customizable**: Easy to extend and modify
 - ✅ **CLI Tool**: Quick installation in any project
 
 ## Installation
 
-**For GitHub Copilot:**
+**For GitHub Copilot (project):**
 
 ```bash
 npx @silverassist/agents-toolkit@latest install
 ```
 
+**For GitHub Copilot (global — all projects):**
+
+```bash
+npx @silverassist/agents-toolkit@latest install --global
+```
+
 **For Claude Code:**
 
 ```bash
@@ -141,6 +148,26 @@ AGENTS.md                             # Project instructions for Codex (project
     └── testing-patterns/
 ```
 
+### Global Install (Optional)
+
+Install once and have instructions, prompts, and skills available across **all your projects** without running `install` in each one:
+
+```bash
+# Install everything to ~/.copilot/
+npx @silverassist/agents-toolkit@latest install --global
+
+# Filter by stack/tracker
+npx @silverassist/agents-toolkit@latest install --global --stack wordpress
+npx @silverassist/agents-toolkit@latest install --global --stack react --tracker github
+
+# Update global install
+npx @silverassist/agents-toolkit@latest update --global
+```
+
+This installs to `~/.copilot/` (instructions, prompts, skills) and creates `~/.agents-toolkit.json` as the global config. Project-level files (AGENTS.md, copilot-instructions.md) are skipped since they are project-specific.
+
+> **Config resolution order:** CLI flags → project `.agents-toolkit.json` → global `~/.agents-toolkit.json` → defaults.
+
 ### Configure Project (Optional)
 
 Update `.agents-toolkit.json` in your project root (created automatically):
@@ -218,6 +245,7 @@ npx @silverassist/agents-toolkit@latest install [options]
 
 | Option | Description |
 |--------|-------------|
+| `--global`, `-g` | Install to `~/.copilot/` for all projects (user-level) |
 | `--target <name>` | Target installer: `copilot`, `claude`, or `codex` |
 | `--stack <name>` | Filter by tech stack: `react`, `wordpress`, or `all` (default) |
 | `--tracker <name>` | Filter by issue tracker: `github`, `jira`, or `all` (default) |
@@ -269,6 +297,11 @@ npx @silverassist/agents-toolkit@latest install --tracker jira
 # Combine stack + tracker
 npx @silverassist/agents-toolkit@latest install --stack react --tracker github
 npx @silverassist/agents-toolkit@latest install --stack wordpress --tracker jira --claude
+
+# Global install (all projects, no per-project setup needed)
+npx @silverassist/agents-toolkit@latest install --global
+npx @silverassist/agents-toolkit@latest install --global --stack wordpress
+npx @silverassist/agents-toolkit@latest update --global
 ```
 
 ### update
@@ -296,9 +329,11 @@ npx @silverassist/agents-toolkit@latest list
 | Scenario | Command |
 |----------|---------|
 | First time installation (Copilot) | `install` |
-| First time installation (Any target) | `install --target <copilot|claude|codex>` |
+| First time installation (Any target) | `install --target <copilot\|claude\|codex>` |
 | First time installation (Claude) | `install --claude` |
 | First time installation (Codex) | `install --codex` |
+| Install once for all projects | `install --global` |
+| Update global install | `update --global` |
 | Add only new files (keep customizations) | `install` |
 | Get latest version (discard customizations) | `update` |
 | Update specific category only | `update --prompts-only` |

package/bin/cli.js

@@ -147,19 +147,35 @@ function info(message) {
   log(`ℹ️  ${message}`, 'blue');
 }
 
+/**
+ * Get the user home directory
+ * @returns {string} Path to home directory
+ */
+function getHomeDir() {
+  return process.env.HOME || process.env.USERPROFILE || '';
+}
+
 /**
  * Get the target directory for Copilot installation
- * @returns {string} Path to .github directory
+ * @param {boolean} global - Install to user-level ~/.copilot/
+ * @returns {string} Path to .github or ~/.copilot directory
  */
-function getTargetDir() {
+function getTargetDir(global = false) {
+  if (global) {
+    return path.join(getHomeDir(), '.copilot');
+  }
   return path.join(process.cwd(), '.github');
 }
 
 /**
  * Get the target directory for Claude Code installation
+ * @param {boolean} global - Install to user-level ~/.claude/
  * @returns {string} Path to .claude directory
  */
-function getClaudeTargetDir() {
+function getClaudeTargetDir(global = false) {
+  if (global) {
+    return path.join(getHomeDir(), '.claude');
+  }
   return path.join(process.cwd(), '.claude');
 }
 
@@ -285,20 +301,21 @@ function getChangeCount(result, dryRun) {
   return dryRun ? result.planned : result.written;
 }
 
-function ensureConfigFile({ dryRun = false } = {}) {
-  const configPath = path.join(process.cwd(), '.agents-toolkit.json');
+function ensureConfigFile({ dryRun = false, global = false } = {}) {
+  const configDir = global ? getHomeDir() : process.cwd();
+  const configPath = path.join(configDir, '.agents-toolkit.json');
 
   if (fs.existsSync(configPath)) {
     return { written: 0, planned: 0 };
   }
 
   if (dryRun) {
-    info('Would create .agents-toolkit.json');
+    info(`Would create ${global ? '~' : '.'}/.agents-toolkit.json`);
     return { written: 0, planned: 1 };
   }
 
   fs.writeFileSync(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2));
-  success('Created .agents-toolkit.json config file');
+  success(`Created ${global ? '~' : '.'}/.agents-toolkit.json config file`);
   return { written: 1, planned: 1 };
 }
 
@@ -422,10 +439,11 @@ function installGitBasedTarget(options = {}, target = 'copilot') {
     force = false,
     append = false,
     dryRun = false,
+    global: isGlobal = false,
     filters = { stack: 'all', tracker: 'all' },
   } = options;
   const isCodex = target === 'codex';
-  const targetDir = getTargetDir();
+  const targetDir = getTargetDir(isGlobal);
   const scope = getInstallScope(options);
   let totalChanges = 0;
 
@@ -437,7 +455,11 @@ function installGitBasedTarget(options = {}, target = 'copilot') {
   const promptsFilter = makeFilter('prompts');
   const partialsFilter = makeFilter('partials');
 
-  log(isCodex ? '\n⚡ Codex Installer\n' : '\n📦 Agents Toolkit Installer\n', 'bright');
+  log(isCodex ? '\n⚡ Codex Installer\n' : isGlobal ? '\n🌐 Agents Toolkit Global Installer\n' : '\n📦 Agents Toolkit Installer\n', 'bright');
+
+  if (isGlobal) {
+    info(`Target: ${targetDir}\n`);
+  }
 
   if (dryRun) {
     info('Dry run mode - no files will be copied\n');
@@ -473,15 +495,15 @@ function installGitBasedTarget(options = {}, target = 'copilot') {
     }
   }
 
-  const configResult = ensureConfigFile({ dryRun });
+  const configResult = ensureConfigFile({ dryRun, global: isGlobal });
   totalChanges += getChangeCount(configResult, dryRun);
 
-  if (scope.shouldInstallInstructions && !isCodex) {
+  if (!isGlobal && scope.shouldInstallInstructions && !isCodex) {
     const copilotInstructionsResult = installCopilotInstructions({ targetDir, dryRun });
     totalChanges += getChangeCount(copilotInstructionsResult, dryRun);
   }
 
-  if (scope.shouldInstallInstructions) {
+  if (!isGlobal && scope.shouldInstallInstructions) {
     const agentsTemplatePath = isCodex
       ? path.join(TEMPLATES_DIR, 'agents', 'AGENTS.codex.md')
       : path.join(TEMPLATES_DIR, 'agents', 'AGENTS.md');
@@ -495,14 +517,20 @@ function installGitBasedTarget(options = {}, target = 'copilot') {
   } else if (totalChanges > 0) {
     success(`Installation complete! ${totalChanges} files installed.`);
     console.log('');
-    info('Next steps:');
-    console.log('  1. Update .agents-toolkit.json with your Jira project key');
-    if (isCodex) {
-      console.log('  2. Review AGENTS.md in the project root');
-      console.log('  3. Run Codex from this project root');
+    if (isGlobal) {
+      info('Next steps:');
+      console.log(`  1. Update ~/.agents-toolkit.json with your defaults`);
+      console.log('  2. Instructions/prompts/skills are now available globally in VS Code');
     } else {
-      console.log('  2. Configure Atlassian MCP in VS Code');
-      console.log('  3. Run prompts via Command Palette > "GitHub Copilot: Run Prompt"');
+      info('Next steps:');
+      console.log('  1. Update .agents-toolkit.json with your Jira project key');
+      if (isCodex) {
+        console.log('  2. Review AGENTS.md in the project root');
+        console.log('  3. Run Codex from this project root');
+      } else {
+        console.log('  2. Configure Atlassian MCP in VS Code');
+        console.log('  3. Run prompts via Command Palette > "GitHub Copilot: Run Prompt"');
+      }
     }
   } else {
     warn('No new files installed. Use --force to overwrite existing files.');
@@ -531,10 +559,10 @@ function installCodex(options = {}) {
  * @param {Object} options - Install options
  */
 function installClaude(options = {}) {
-  const { force = false, dryRun = false, filters = { stack: 'all', tracker: 'all' } } = options;
+  const { force = false, dryRun = false, global: isGlobal = false, filters = { stack: 'all', tracker: 'all' } } = options;
   const scope = getInstallScope(options);
-  const claudeDir = getClaudeTargetDir();
-  const githubDir = getTargetDir();
+  const claudeDir = getClaudeTargetDir(isGlobal);
+  const githubDir = getTargetDir(isGlobal);
   let totalChanges = 0;
 
   const makeFilter = (category) => (name) => {
@@ -588,7 +616,7 @@ function installClaude(options = {}) {
     }
   }
 
-  if (scope.shouldInstallInstructions) {
+  if (!isGlobal && scope.shouldInstallInstructions) {
     const claudeMdPath = path.join(process.cwd(), 'CLAUDE.md');
     const claudeMdTemplate = path.join(TEMPLATES_DIR, 'agents', 'CLAUDE.md');
 
@@ -608,7 +636,7 @@ function installClaude(options = {}) {
     }
   }
 
-  const configResult = ensureConfigFile({ dryRun });
+  const configResult = ensureConfigFile({ dryRun, global: isGlobal });
   totalChanges += getChangeCount(configResult, dryRun);
 
   console.log('');
@@ -617,10 +645,16 @@ function installClaude(options = {}) {
   } else if (totalChanges > 0) {
     success(`Installation complete! ${totalChanges} files installed.`);
     console.log('');
-    info('Next steps:');
-    console.log('  1. Update .agents-toolkit.json with your Jira project key');
-    console.log('  2. Configure Atlassian MCP in Claude Code settings');
-    console.log('  3. Run slash commands with /analyze-ticket, /work-ticket, etc.');
+    if (isGlobal) {
+      info('Next steps:');
+      console.log('  1. Update ~/.agents-toolkit.json with your defaults');
+      console.log('  2. Claude commands are now available globally');
+    } else {
+      info('Next steps:');
+      console.log('  1. Update .agents-toolkit.json with your Jira project key');
+      console.log('  2. Configure Atlassian MCP in Claude Code settings');
+      console.log('  3. Run slash commands with /analyze-ticket, /work-ticket, etc.');
+    }
   } else {
     warn('No new files installed. Use --force to overwrite existing files.');
   }
@@ -700,6 +734,7 @@ function showHelp() {
   console.log('');
   log('Options:', 'cyan');
   console.log('  --force, -f         Overwrite existing files');
+  console.log('  --global, -g        Install to ~/.copilot/ (user-level, all projects)');
   console.log('  --target <name>     Target installer: copilot | claude | codex');
   console.log('  --stack <name>      Filter by stack: react | wordpress | all (default: all)');
   console.log('  --tracker <name>    Filter by tracker: jira | github | all (default: all)');
@@ -714,7 +749,9 @@ function showHelp() {
 
   console.log('');
   log('Examples:', 'cyan');
-  console.log('  npx agents-toolkit install                          # All content');
+  console.log('  npx agents-toolkit install                          # All content to .github/');
+  console.log('  npx agents-toolkit install --global                 # All content to ~/.copilot/');
+  console.log('  npx agents-toolkit install --global --stack react   # React only to ~/.copilot/');
   console.log('  npx agents-toolkit install --stack react            # React/TS only');
   console.log('  npx agents-toolkit install --stack wordpress        # PHP/WordPress only');
   console.log('  npx agents-toolkit install --tracker github         # GitHub Issues workflow');
@@ -779,6 +816,7 @@ function parseArgs() {
 
   const options = {
     force: flags.includes('--force') || flags.includes('-f'),
+    global: flags.includes('--global') || flags.includes('-g'),
     promptsOnly: flags.includes('--prompts-only'),
     partialsOnly: flags.includes('--partials-only'),
     skillsOnly: flags.includes('--skills-only'),
@@ -841,6 +879,7 @@ function resolveInstallTarget(options = {}) {
 
 /**
  * Resolve stack and tracker filters from flags or config file
+ * Resolution order: CLI flags > project config > global config > defaults
  * @param {Object} options - Parsed CLI options
  * @returns {{ stack: string, tracker: string }} Resolved filters
  */
@@ -851,6 +890,19 @@ function resolveFilters(options = {}) {
   let stack = 'all';
   let tracker = 'all';
 
+  // Check global config first (~/.agents-toolkit.json)
+  const globalConfigPath = path.join(getHomeDir(), '.agents-toolkit.json');
+  if (fs.existsSync(globalConfigPath)) {
+    try {
+      const config = JSON.parse(fs.readFileSync(globalConfigPath, 'utf-8'));
+      if (config.stack) stack = config.stack;
+      if (config.tracker) tracker = config.tracker;
+    } catch {
+      // Ignore invalid config
+    }
+  }
+
+  // Project config overrides global
   const configPath = path.join(process.cwd(), '.agents-toolkit.json');
   if (fs.existsSync(configPath)) {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@silverassist/agents-toolkit",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Reusable AI agent prompts for development workflows with Jira integration — supports GitHub Copilot, Claude Code, and Codex",
   "author": "Santiago Ramirez",
   "license": "PolyForm-Noncommercial-1.0.0",

package/src/index.js

@@ -3,7 +3,7 @@
  * @module @silverassist/agents-toolkit
  */
 
-export const VERSION = "2.0.0";
+export const VERSION = "2.2.0";
 
 export const PROMPTS = {
   workflow: [
@@ -37,6 +37,7 @@ export const SKILLS = [
   "component-architecture",
   "domain-driven-design",
   "testing-patterns",
+  "ai-seo-optimization",
 ];
 
 // Claude Code equivalents

package/templates/shared/prompts/audit-ai-seo.prompt.md

@@ -0,0 +1,107 @@
+---
+agent: agent
+description: Run a comprehensive AI SEO optimization audit on the current project. Checks agent-friendly UX, E-E-A-T signals, content quality, technical SEO, and structured data.
+---
+
+# AI SEO Optimization Audit
+
+Run a comprehensive audit of this project for Google AI Search visibility and browser agent readiness.
+
+## Context
+
+Use the `ai-seo-optimization` skill as reference for all criteria. This audit follows Google's official AI Optimization Guide (May 2026).
+
+## Audit Steps
+
+### 1. Technical Baseline
+
+> **Scope**: The checks below use Next.js App Router terminology (Server Components, `generateMetadata`). For non-Next.js projects, adapt to the equivalent patterns (e.g., SSR/SSG for content rendering, `<meta>` tags for metadata).
+
+Check the following in the codebase:
+
+- [ ] Pages use Server Components or SSR (content is rendered server-side, not client-only)
+- [ ] No `nosnippet` or `data-nosnippet` on key content
+- [ ] Metadata (title, description, OpenGraph) is set for all pages
+- [ ] Canonical tags are properly set (no duplicates)
+- [ ] XML sitemap exists and includes all valuable pages
+- [ ] `robots.txt` doesn't block critical resources
+
+### 2. Agent-Friendly UX
+
+Audit components for:
+
+- [ ] No `<div onClick>` patterns (must use `<button>` or `<a>`)
+- [ ] All `<input>` elements have associated `<label htmlFor>`
+- [ ] Heading hierarchy is correct (`h1` → `h2` → `h3`, no skips)
+- [ ] Skip-to-content link exists as first focusable element
+- [ ] Interactive elements have `cursor: pointer`
+- [ ] No ghost overlays blocking interactive elements
+- [ ] All interactive elements have accessible names
+
+### 3. E-E-A-T Signals (YMYL Sites)
+
+Check for existence of:
+
+- [ ] Author pages with credentials and `Person` schema
+- [ ] About/Mission page with team information
+- [ ] Methodology or "How we rate" page
+- [ ] Data source disclosures
+- [ ] Contact information easily accessible
+- [ ] Privacy policy and terms linked from all pages
+- [ ] Content dates (published/modified) visible
+
+### 4. Content Quality Assessment
+
+Review top landing pages for:
+
+- [ ] Unique data or insights not available elsewhere
+- [ ] First-hand experience signals
+- [ ] Expert commentary with attribution
+- [ ] Interactive tools or calculators
+- [ ] No thin/commodity content on indexed pages
+
+### 5. Structured Data Validation
+
+Check JSON-LD implementation:
+
+- [ ] `LocalBusiness` on community/location pages (with address, geo, priceRange)
+- [ ] `Person` on author pages (with knowsAbout, jobTitle)
+- [ ] `Article` on blog posts (with author, datePublished, dateModified)
+- [ ] `BreadcrumbList` on all pages
+- [ ] `Organization` on homepage
+- [ ] No validation errors (test with Rich Results Test)
+
+### 6. Performance & Core Web Vitals
+
+- [ ] LCP < 2.5s on key templates
+- [ ] CLS < 0.1 (no layout shifts)
+- [ ] INP < 200ms (responsive interactions)
+- [ ] Images have explicit dimensions
+- [ ] Fonts use `display: swap`
+
+## Output Format
+
+Provide results as:
+
+```markdown
+## AI SEO Audit Results — [Project Name]
+
+### Score Summary
+| Area | Status | Score |
+|------|--------|-------|
+| Technical Baseline | 🟢/🟡/🔴 | X/Y |
+| Agent-Friendly UX | 🟢/🟡/🔴 | X/Y |
+| E-E-A-T Signals | 🟢/🟡/🔴 | X/Y |
+| Content Quality | 🟢/🟡/🔴 | X/Y |
+| Structured Data | 🟢/🟡/🔴 | X/Y |
+| Performance | 🟢/🟡/🔴 | X/Y |
+
+### Critical Issues (Fix Immediately)
+- ...
+
+### Improvements (High Impact)
+- ...
+
+### Recommendations (Nice to Have)
+- ...
+```

package/templates/shared/skills/ai-seo-optimization/SKILL.md

@@ -0,0 +1,354 @@
+---
+name: ai-seo-optimization
+description: Optimize websites for Google's generative AI features and browser agents. Use when asked to "optimize for AI search", "AI overview", "agent-friendly audit", "E-E-A-T assessment", "AI SEO", "generative search optimization", or "audit accessibility for agents".
+---
+
+# AI SEO Optimization Skill
+
+Comprehensive guide for optimizing Next.js sites for Google's generative AI features (AI Overviews, AI Mode) and emerging browser agent interactions.
+
+> **Source**: [Google AI Optimization Guide](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide) (May 2026)
+> **Companion**: [Build Agent-Friendly Websites](https://web.dev/articles/ai-agent-site-ux) (April 2026)
+
+---
+
+## Core Principle
+
+**AI Search optimization IS SEO.** There is no separate "AEO" or "GEO" discipline. Google's AI features use the same Search index, the same ranking signals, and the same content quality assessments. If your page is well-optimized for Search, it's well-optimized for AI features.
+
+---
+
+## 1. How Google's AI Features Discover Content
+
+Google's generative AI features use **Retrieval-Augmented Generation (RAG)**:
+
+1. User query triggers **query fan-out** (multiple sub-queries)
+2. Each sub-query retrieves pages from the **existing Search index**
+3. AI synthesizes answers from retrieved content
+4. Citations link back to source pages
+
+**Requirements for inclusion:**
+- Page MUST be indexed (verify in Search Console)
+- Page MUST allow snippets (no `nosnippet` meta directive)
+- Content MUST be server-rendered (not client-only JavaScript)
+- Content MUST be accessible to Googlebot (no login walls for indexed content)
+
+---
+
+## 2. Agent-Friendly UX Audit Checklist
+
+Browser agents (Google's Mariner, OpenAI's Operator, etc.) interact with sites through three channels:
+
+1. **Screenshots** — Vision model identifies elements visually
+2. **HTML/DOM** — Understands nesting, hierarchy, relationships
+3. **Accessibility tree** — Roles, names, states of interactive elements
+
+### Semantic HTML
+
+- [ ] All clickable elements use `<button>` or `<a href>` (NEVER `<div onClick>` or `<span onClick>`)
+- [ ] All form inputs have associated `<label htmlFor="id">` (not just placeholder text)
+- [ ] Heading hierarchy is logical (`h1` > `h2` > `h3`, no skips)
+- [ ] Lists use `<ul>`/`<ol>`/`<li>` (not styled divs)
+- [ ] Tables use `<table>` with `<th>` headers for tabular data
+- [ ] Navigation uses `<nav>` with proper `aria-label`
+- [ ] Main content wrapped in `<main>`
+- [ ] Sections use `<section>` or `<article>` with headings
+
+### Accessibility Tree
+
+- [ ] All interactive elements have accessible names (visible text, `aria-label`, or `aria-labelledby`)
+- [ ] ARIA roles used ONLY when semantic HTML isn't available
+- [ ] Skip-to-content link is first focusable element
+- [ ] Focus order matches visual order (`tabindex` not misused)
+- [ ] Modal dialogs use `<dialog>` or proper `role="dialog"` with focus trapping
+- [ ] Dynamic content changes announced via `aria-live` regions
+
+### Visual Stability
+
+- [ ] No layout shifts after load (CLS < 0.1)
+- [ ] Interactive elements have stable positions (no jumping during scroll)
+- [ ] No transparent overlays blocking clickable elements (ghost overlays)
+- [ ] All actionable elements meet minimum target size of 24×24 CSS px (WCAG 2.2 SC 2.5.8)
+- [ ] Images have explicit `width` and `height` (prevent layout shift)
+
+### CSS Signals for Agents
+
+- [ ] `cursor: pointer` on all clickable elements (strong actionability signal)
+- [ ] Focus indicators visible on keyboard navigation (`:focus-visible` styles)
+- [ ] Interactive states are distinct (`:hover`, `:active`, `:focus`)
+- [ ] Disabled elements have `pointer-events: none` and `opacity` reduction
+- [ ] No `display: none` on elements that should be accessible to screen readers
+
+### Form Accessibility (Critical for Agent Interactions)
+
+- [ ] Every `<input>` has an associated `<label>` with `htmlFor`
+- [ ] Required fields marked with `aria-required="true"` or `required` attribute
+- [ ] Error messages linked with `aria-describedby`
+- [ ] Form groups use `<fieldset>` with `<legend>`
+- [ ] Submit buttons have clear text (not just icons)
+- [ ] Autocomplete attributes set for common fields (`name`, `email`, `tel`, `address-*`)
+
+---
+
+## 3. E-E-A-T Assessment (Critical for YMYL Sites)
+
+For sites dealing with health, finance, safety, or life decisions (Your Money or Your Life), E-E-A-T signals are critical for AI citation.
+
+### Experience
+
+- [ ] Content demonstrates first-hand knowledge (not aggregated summaries)
+- [ ] Real user reviews and testimonials with attribution
+- [ ] Case studies or examples from actual experience
+- [ ] Visual evidence (photos, videos) of real experiences
+
+### Expertise
+
+- [ ] Author credentials displayed clearly (degrees, certifications, years of experience)
+- [ ] Author pages exist with `Person` schema and `knowsAbout` properties
+- [ ] Content reviewed by subject matter experts (editorial review notice)
+- [ ] Specialized terminology used correctly with explanations for lay readers
+
+### Authoritativeness
+
+- [ ] About page with team credentials, methodology, and mission
+- [ ] Clear data source disclosures ("Where our data comes from")
+- [ ] "How we rate" or methodology explanation pages
+- [ ] Institutional authority signals (partnerships, certifications, media mentions)
+- [ ] Consistent NAP (Name, Address, Phone) across web presence
+
+### Trustworthiness
+
+- [ ] Contact information easily findable (not buried in footer only)
+- [ ] Privacy policy and terms of service accessible from all pages
+- [ ] Transparent pricing when applicable (no hidden fees)
+- [ ] Content is accurate and up-to-date (publish/update dates visible)
+- [ ] Corrections policy or update log for changed information
+- [ ] HTTPS enforced, security headers properly configured
+
+---
+
+## 4. Non-Commodity Content Criteria
+
+Google's AI features prefer content that provides unique value. Assess content against these criteria:
+
+### Non-Commodity Content (Google Favors)
+
+- **Unique data analysis** from proprietary sources (not publicly available datasets)
+- **First-hand experiences** and detailed reviews with specific details
+- **Expert-led insights** that go beyond commonly available information
+- **Original research** with methodology and reproducible findings
+- **Interactive tools** and calculators with unique logic
+- **Comparison data** that requires effort to compile (pricing, availability)
+- **Local knowledge** that can't be found without physical presence
+
+### Commodity Content (Avoid or Upgrade)
+
+- ❌ "X Tips for [topic]" without unique insights (generic listicles)
+- ❌ Summaries of information freely available elsewhere
+- ❌ Generic advice easily produced by any AI model
+- ❌ Content created primarily for keyword targeting
+- ❌ Thin pages with minimal original value
+- ❌ Automatically generated content without expert review
+
+### Content Upgrade Strategy
+
+For existing commodity content, improve by adding:
+1. **Unique data points** from proprietary sources
+2. **Expert commentary** with attribution
+3. **Real examples** with specifics (names, dates, outcomes)
+4. **Interactive elements** (calculators, comparison tools)
+5. **Original media** (photographs, diagrams, video)
+
+---
+
+## 5. Technical SEO for AI Discovery
+
+### Indexing & Crawlability
+
+- [ ] All key pages indexed (verify in Google Search Console)
+- [ ] No accidental `noindex` directives on important pages
+- [ ] No `nosnippet` or `data-nosnippet` blocking content extraction
+- [ ] `robots.txt` doesn't block critical resources
+- [ ] Crawl budget optimized (no low-value pages wasting crawl resources)
+- [ ] XML sitemap includes all valuable pages (updated automatically)
+
+### Server-Side Rendering
+
+- [ ] Critical content renders on server (not client-only JavaScript)
+- [ ] Dynamic content accessible without user interaction
+- [ ] No infinite scroll hiding content from crawlers
+- [ ] Metadata generated server-side (`generateMetadata` in Next.js)
+
+### URL & Content Structure
+
+- [ ] Canonical tags correctly set (prevent duplicate content confusion)
+- [ ] Internal linking connects related content (topic clusters)
+- [ ] Breadcrumb navigation with schema markup
+- [ ] Clean URL structure reflecting content hierarchy
+- [ ] Pagination handled with view-all option or clear next/previous links (note: `rel="next"`/`rel="prev"` is no longer used as a Google indexing signal)
+
+### Performance & Page Experience
+
+- [ ] Core Web Vitals in "Good" range (LCP < 2.5s, INP < 200ms, CLS < 0.1)
+- [ ] HTTPS enforced with valid certificate
+- [ ] No intrusive interstitials blocking content
+- [ ] Mobile-friendly (responsive design)
+- [ ] Font loading doesn't cause layout shift (`display: swap`)
+
+---
+
+## 6. Structured Data Patterns
+
+Structured data helps Google understand content relationships. While NOT required for AI features, it improves overall search presence.
+
+### LocalBusiness (Community/Location Pages)
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "LocalBusiness",
+  "name": "Community Name",
+  "address": {
+    "@type": "PostalAddress",
+    "streetAddress": "123 Main St",
+    "addressLocality": "City",
+    "addressRegion": "FL",
+    "postalCode": "33101"
+  },
+  "geo": { "@type": "GeoCoordinates", "latitude": 25.76, "longitude": -80.19 },
+  "telephone": "+1-555-0100",
+  "priceRange": "$$-$$$",
+  "openingHours": "Mo-Su 00:00-24:00",
+  "aggregateRating": { "@type": "AggregateRating", "ratingValue": "4.5", "reviewCount": "28" },
+  "sameAs": ["https://g.page/community", "https://facebook.com/community"]
+}
+```
+
+### Person (Author/Expert Pages)
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Person",
+  "name": "Author Name",
+  "jobTitle": "Senior Care Advisor",
+  "knowsAbout": ["Assisted Living", "Memory Care", "VA Benefits"],
+  "sameAs": ["https://linkedin.com/in/author"],
+  "worksFor": { "@type": "Organization", "name": "Company Name" }
+}
+```
+
+### Article (Blog/Resource Posts)
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "headline": "Article Title",
+  "author": { "@type": "Person", "name": "Author", "url": "/about/authors/slug" },
+  "datePublished": "2026-01-15",
+  "dateModified": "2026-05-01",
+  "publisher": { "@type": "Organization", "name": "Site Name" }
+}
+```
+
+### FAQPage (FAQ Sections)
+
+```json
+{
+  "@type": "FAQPage",
+  "mainEntity": [
+    {
+      "@type": "Question",
+      "name": "What is the cost of assisted living?",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "The average cost varies by state..."
+      }
+    }
+  ]
+}
+```
+
+---
+
+## 7. What NOT to Do (Mythbusting)
+
+These are explicitly confirmed as **unnecessary or harmful** by Google:
+
+| ❌ Don't Do This | Why |
+|------------------|-----|
+| Create `llms.txt` files | Google doesn't treat them specially |
+| "Chunk" content into tiny pieces | Google handles multi-topic pages fine |
+| Rewrite content "for AI" (AEO/GEO) | AI understands synonyms and natural language |
+| Seek inauthentic brand mentions | Spam systems detect and penalize this |
+| Overfocus on structured data alone | Helpful but NOT required for AI features |
+| Create separate pages for query variations | Violates scaled content abuse policy |
+| Add special "AI-readable" Markdown files | Standard HTML is the input format |
+| Use hidden text for AI consumption | Cloaking violation |
+| Stuff keywords "for LLM training" | Spam — same old rules apply |
+| Disallow AI crawlers (GPTBot, etc.) | Google uses Googlebot only — blocking others has no effect on Google AI |
+
+---
+
+## 8. Implementation Priorities
+
+### Quick Wins (< 1 day each)
+
+1. Add `cursor: pointer` CSS for all interactive elements
+2. Add skip-to-content link to root layout
+3. Verify no `nosnippet` directives on key pages
+4. Check all forms have proper `<label>` associations
+5. Verify heading hierarchy on top landing pages
+
+### Medium Effort (1-3 days each)
+
+1. Semantic HTML audit of all components (replace `<div onClick>`)
+2. Author/expert page creation with Person schema
+3. "About Our Data" / methodology page
+4. Image alt text quality audit and improvement
+5. Internal linking optimization
+
+### High Effort (1+ week each)
+
+1. Non-commodity content strategy and execution
+2. Interactive tools (calculators, comparison widgets)
+3. Comprehensive accessibility audit and remediation
+4. E-E-A-T content enrichment across all page types
+5. Video/media content creation
+
+---
+
+## 9. Audit Workflow
+
+When asked to audit a site for AI optimization, follow this order:
+
+1. **Technical baseline** — Verify indexing, SSR, canonical tags, Core Web Vitals
+2. **Agent-friendly audit** — Run through Section 2 checklist on key templates
+3. **E-E-A-T assessment** — Evaluate Section 3 for YMYL compliance
+4. **Content quality** — Assess top pages against Section 4 criteria
+5. **Structured data** — Validate existing schema, identify gaps
+6. **Recommendations** — Prioritize by impact/effort ratio
+
+---
+
+## 10. Monitoring & Measurement
+
+| Metric | Tool | What to Track |
+|--------|------|---------------|
+| AI Overview appearances | Google Search Console → Search Appearance | Citation frequency |
+| Organic CTR from AI features | GSC filtered by AI appearance type | Click-through trends |
+| Core Web Vitals | PageSpeed Insights / CrUX | All "Good" status |
+| Structured data validity | Rich Results Test | 0 errors, 0 warnings |
+| Accessibility score | Lighthouse CI | 95+ target |
+| Index coverage | GSC → Indexing | No regressions |
+
+---
+
+## References
+
+- [Google AI Optimization Guide](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide)
+- [Build Agent-Friendly Websites](https://web.dev/articles/ai-agent-site-ux)
+- [Creating Helpful, Reliable, People-First Content](https://developers.google.com/search/docs/fundamentals/creating-helpful-content)
+- [Google Search Quality Rater Guidelines](https://services.google.com/fh/files/misc/hsw-sqrg.pdf)
+- [Universal Commerce Protocol (UCP)](https://ucp.dev/latest/)