fix(agent-docs): update AI.dev guides + script UX after single-source migration

Followup audit of the single-source-of-truth agent-docs rollout. Several
AI.dev prompts and skills still taught agents the old 8-file pattern (which
would re-introduce drift) and the generator script emitted a misleading
summary in --no-commit mode.

AI.dev guides:
- Delete AI.dev/SKILLS/update-agent-docs.md — entire doc taught the old
  8-file pattern. Canonical reference is now
  .windsurf/workflows/repo_update-agent-docs.md.
- AI.dev/SKILLS/index.md + README.md: replace dangling 'Update Agent
  Documentation' link with pointers to agent-behavior-guidelines.md,
  agent-onboarding.md, and the workflow doc.
- AI.dev/SKILLS/scan-repo-context.md: remove instructions to read
  .windsurfrules / write .cursorrules. Point at the canonical behavior file.
- AI.dev/PROMPTS/new-product-scaffold.md: remove .windsurfrules and CLAUDE.md
  from the scaffold tree. Add deprecated-files callout + regeneration hint.
- AI.dev/PROMPTS/agents-md-sync.md: drop 'Step 4 update CLAUDE.md', point at
  the generator instead. Remove CLAUDE.md from `git add`.
- AI.dev/PROMPTS/ecosystem-audit.md: replace 'CLAUDE.md exists?' with
  'canonical-behavior-pointer block present? legacy files absent?'.

Script UX:
- scripts/update-agent-docs.sh: stop printing 'All repos already in sync'
  when --no-commit suppressed commits or --dry-run was used. Emit accurate
  per-mode summaries instead.

AI.dev/PROMPTS/agents-md-sync.md

@@ -77,15 +77,25 @@ For each drift found:
 - Preserve all existing comments and documentation
 - Keep formatting consistent with other repos
 
-### Step 4: Update CLAUDE.md
+### Step 4: Regenerate Derived Files
 
-If AGENTS.md changed significantly, also sync CLAUDE.md (the Claude Code-specific instruction file).
+If AGENTS.md changed significantly, regenerate the derived agent files
+(`.github/copilot-instructions.md`, `.aider.conf.yml`, `.editorconfig`) via:
+
+```bash
+cd ../learning_ai_common_plat
+bash scripts/update-agent-docs.sh
+```
+
+The canonical-behavior-pointer block at the top of AGENTS.md is auto-managed —
+do not edit it by hand. Legacy files (`CLAUDE.md`, `.cursorrules`,
+`.windsurfrules`, `.clinerules`) are deprecated and should not exist.
 
 ### Step 5: Commit Per Repo
 
 ```bash
 cd <repo>
-git add AGENTS.md CLAUDE.md
+git add AGENTS.md
 git commit -m "docs(agents): sync AGENTS.md with current repo state
 
 - Updated: <sections that changed>

AI.dev/PROMPTS/ecosystem-audit.md

@@ -77,9 +77,10 @@ pnpm audit
 ```
 
 ### 7. Documentation Currency
-- AGENTS.md matches current layout?
+- AGENTS.md exists and matches current layout?
+- AGENTS.md contains the canonical-behavior-pointer block? (`bash scripts/check-agent-docs-drift.sh`)
 - README.md has setup instructions?
-- CLAUDE.md exists?
+- Legacy agent files removed? (`.cursorrules`, `.windsurfrules`, `.clinerules`, `CLAUDE.md` — replaced by single-source-of-truth pattern)
 
 ### 8. Git Hygiene
 - Any repos with uncommitted changes?

AI.dev/PROMPTS/new-product-scaffold.md

@@ -42,13 +42,14 @@ learning_ai_<repo_name>/
 ├── scripts/
 │   ├── secret-scan-repo.sh
 │   └── secret-scan-staged.sh
-├── .editorconfig
+├── .editorconfig                # Generated by update-agent-docs.sh
+├── .aider.conf.yml              # Generated by update-agent-docs.sh
 ├── .gitignore
+├── .github/
+│   └── copilot-instructions.md  # Generated by update-agent-docs.sh (thin pointer)
 ├── .npmrc                       # From canonical template (never hand-edit)
 ├── .nvmrc                       # "22"
-├── .windsurfrules
+├── AGENTS.md                    # Hand-maintained; canonical pointer auto-prepended
-├── AGENTS.md
-├── CLAUDE.md
 ├── README.md
 ├── package.json                 # Root workspace scripts
 ├── pnpm-workspace.yaml
@@ -56,6 +57,17 @@ learning_ai_<repo_name>/
 └── tsconfig.json
 ```
 
+> **Deprecated files — do NOT create:** `.cursorrules`, `.windsurfrules`,
+> `.clinerules`, `CLAUDE.md`. These were replaced by the single-source-of-truth
+> pattern. Agents read `AGENTS.md` plus the canonical behavior file at
+> `../learning_ai_common_plat/AI.dev/SKILLS/agent-behavior-guidelines.md`.
+>
+> After adding the new repo to
+> `learning_ai_common_plat/.windsurf/workflows/repos.txt`, run
+> `bash ../learning_ai_common_plat/scripts/update-agent-docs.sh`
+> to populate `.editorconfig`, `.aider.conf.yml`, and
+> `.github/copilot-instructions.md`.
+
 ### 2. Create `shared/product.json`
 
 ```json

AI.dev/SKILLS/README.md

@@ -76,7 +76,7 @@ Each skill follows a consistent format:
 | Release iOS app            | [iOS Release](./ios-release.md)                      | 🚀 Release & Deployment          |
 | Generate store assets      | [Generate Store Assets](./generate-store-assets.md)  | 🚀 Release & Deployment          |
 | Ensure mobile code quality | [Mobile Code Quality](./mobile-code-quality.md)      | 📱 Mobile Development            |
-| Update AI docs             | [Update Agent Documentation](./update-agent-docs.md) | 📚 Documentation & Communication |
+| Update AI docs             | `../../.windsurf/workflows/repo_update-agent-docs.md` | 📚 Documentation & Communication |
 | Write tests                | [Test Strategies](./test-strategies.md)              | 🧪 Testing & Quality             |
 | Docker full stack          | [Docker Compose](./docker-compose.md)                | 🔧 Development Workflows         |
 | Security audit             | [Security Auditing](./security-auditing.md)          | 🧪 Testing & Quality             |
@@ -95,7 +95,8 @@ Each skill follows a consistent format:
 - [Desktop Release](./desktop-release.md) - Build and package desktop apps
 - [iOS Release](./ios-release.md) - TestFlight and App Store deployment
 - [Generate Store Assets](./generate-store-assets.md) - Create app store artwork
-- [Update Agent Documentation](./update-agent-docs.md) - Keep AI docs current
+- [Agent Behavior Guidelines](./agent-behavior-guidelines.md) - Canonical agent rules
+- Update agent docs across repos — see `../../.windsurf/workflows/repo_update-agent-docs.md`
 - [Test Strategies](./test-strategies.md) - Comprehensive testing approach
 - [Test Desktop App](./test-desktop-app.md) - Desktop app testing
 - [Test iOS App](./test-ios-app.md) - iOS simulator testing

AI.dev/SKILLS/index.md

@@ -39,7 +39,9 @@
 
 ## 📚 Documentation & Communication
 
-- [Update Agent Documentation](./update-agent-docs.md) - AI assistant documentation
+- [Agent Behavior Guidelines](./agent-behavior-guidelines.md) - Canonical agent behavior rules (Karpathy + ByteLyst)
+- [Agent Onboarding](./agent-onboarding.md) - Read-order index for agents
+- Update agent docs across repos — see `../../.windsurf/workflows/repo_update-agent-docs.md`
 - [Scan Repo Context](./scan-repo-context.md) - Generate comprehensive project context
 - [API Documentation](./api-documentation.md) - REST API documentation patterns
 - [Architecture Documentation](./architecture-documentation.md) - System design docs
@@ -59,7 +61,7 @@
 | Mobile code quality   | [Mobile Code Quality](./mobile-code-quality.md)      | 📱 Mobile Development            |
 | Test desktop app      | [Test Desktop App](./test-desktop-app.md)            | 🧪 Testing & Quality             |
 | Test iOS app          | [Test iOS App](./test-ios-app.md)                    | 🧪 Testing & Quality             |
-| Update AI docs        | [Update Agent Documentation](./update-agent-docs.md) | 📚 Documentation & Communication |
+| Update AI docs        | `../../.windsurf/workflows/repo_update-agent-docs.md` | 📚 Documentation & Communication |
 | Scan repo for context | [Scan Repo Context](./scan-repo-context.md)          | 📚 Documentation & Communication |
 | Write tests           | [Test Strategies](./test-strategies.md)              | 🧪 Testing & Quality             |
 | Docker full stack     | [Docker Compose](./docker-compose.md)                | 🔧 Development Workflows         |

AI.dev/SKILLS/scan-repo-context.md

@@ -36,11 +36,12 @@ Start with high-level understanding:
 
 ```bash
 # Core documentation files
-cat AGENTS.md                    # AI agent guide
+cat AGENTS.md                    # AI agent guide (single per-repo source)
 cat README.md                    # Project overview
 cat ARCHITECTURE.md              # Technical architecture
 cat CONTRIBUTING.md              # Contribution guidelines
-cat .windsurfrules              # Windsurf-specific rules
+cat ../learning_ai_common_plat/AI.dev/SKILLS/agent-behavior-guidelines.md
+                                 # Ecosystem-wide agent behavior rules
 ```
 
 ### Phase 2: Understand Project Structure
@@ -346,13 +347,13 @@ echo "Context documentation generated: $OUTPUT_FILE"
 
 The generated `WINDSURF_CONTEXT.md` is automatically picked up by Windsurf.
 
-### Cursor
+### Cursor / Windsurf / Claude Code / Codex / Cline
 
-Add to `.cursorrules`:
+These agents all read `AGENTS.md` at the repo root. Add references to
-
+`WINDSURF_CONTEXT.md` (or equivalent) inside AGENTS.md so every agent sees it.
-```
+Do not create per-tool config files (`.cursorrules`, `.windsurfrules`,
-Always reference WINDSURF_CONTEXT.md for project understanding
+`.clinerules`, `CLAUDE.md`) — they are deprecated in favour of the canonical
-```
+pointer architecture (see `learning_ai_common_plat/.windsurf/workflows/repo_update-agent-docs.md`).
 
 ### GitHub Copilot
 
@@ -391,7 +392,8 @@ git push
 
 ## Related Skills
 
-- [Update Agent Documentation](./update-agent-docs.md) - For AI-specific docs
+- [Agent Behavior Guidelines](./agent-behavior-guidelines.md) - Canonical agent rules
+- [Agent Onboarding](./agent-onboarding.md) - Read-order index for agents
 - [Architecture Patterns](./architecture-patterns.md) - Understanding architecture
 - [Local Development Setup](./local-development.md) - Setting up to work
 - [Documentation Standards](./documentation-standards.md) - Writing good docs

AI.dev/SKILLS/update-agent-docs.md

@@ -1,384 +0,0 @@
-# Update Agent Documentation Skill
-
-**Description**: Scan all repos and regenerate AI assistant documentation (AGENTS.md, CLAUDE.md, etc.) across the workspace.
-
-## When to Use
-
-- After adding new packages or services
-- When changing coding conventions
-- After architectural changes
-- Periodically to keep docs current
-- When onboarding new AI assistants
-
-## Repositories Covered
-
-| Repo                                  | Path                                                | Scope                      |
-| ------------------------------------- | --------------------------------------------------- | -------------------------- |
-| **learning_voice_ai_agent**           | `$HOME/code/mygh/learning_voice_ai_agent`           | LysnrAI product code       |
-| **learning_ai_common_plat**           | `$HOME/code/mygh/learning_ai_common_plat`           | Shared packages + services |
-| **learning_multimodal_memory_agents** | `$HOME/code/mygh/learning_multimodal_memory_agents` | MindLyst native app        |
-
-## Files Updated Per Repo
-
-| File                              | Tool             | Format                       | Purpose                          |
-| --------------------------------- | ---------------- | ---------------------------- | -------------------------------- |
-| `AGENTS.md`                       | Universal        | Detailed markdown            | Full onboarding guide            |
-| `CLAUDE.md`                       | Claude Code      | Compact markdown (<50 lines) | Quick reference                  |
-| `.cursorrules`                    | Cursor AI        | Plain text                   | Inline completion + chat rules   |
-| `.github/copilot-instructions.md` | GitHub Copilot   | Markdown                     | Code generation rules            |
-| `.windsurfrules`                  | Windsurf/Codeium | Plain text                   | Project rules for memory         |
-| `.clinerules`                     | Cline/Roo Code   | Plain text                   | Mandatory rules + file locations |
-| `.aider.conf.yml`                 | Aider            | YAML                         | Context files, conventions       |
-| `.editorconfig`                   | All editors      | INI                          | Indent, charset, line ending     |
-
-## Phase 1: Gather Current State
-
-### 1. Scan learning_voice_ai_agent
-
-```bash
-cd $HOME/code/mygh/learning_voice_ai_agent
-
-# Find all JS projects
-find . -maxdepth 2 -type f -name "package.json" -not -path "*/node_modules/*" | head -20
-
-# Find Python config
-find . -maxdepth 1 -type f -name "*.py" -o -name "*.toml" -o -name "Makefile" | head -20
-
-# Read key files
-cat AGENTS.md
-cat README_MONO_REPO.md
-cat docker-compose.yml
-cat pyproject.toml
-
-# Check dashboard dependencies
-find admin-dashboard-web user-dashboard-web tracker-dashboard-web -name "package.json" -exec grep "@bytelyst" {} \;
-
-# List lib files
-ls admin-dashboard-web/src/lib/
-ls user-dashboard-web/src/lib/
-ls tracker-dashboard-web/src/lib/
-
-# Count tests
-find tests/ -name "test_*.py" | wc -l
-find admin-dashboard-web/src/app/api -name "route.ts" | wc -l
-
-# Check CI workflows
-ls -la .github/workflows/
-
-# Check service topology
-head -20 run-local-all-services.sh
-```
-
-### 2. Scan learning_ai_common_plat
-
-```bash
-cd $HOME/code/mygh/learning_ai_common_plat
-
-# List all packages
-find packages -maxdepth 2 -name "package.json" -not -path "*/node_modules/*"
-
-# List all services
-find services -maxdepth 2 -name "package.json" -not -path "*/node_modules/*"
-
-# Read key files
-cat AGENTS.md
-cat README.md
-cat pnpm-workspace.yaml
-cat tsconfig.base.json
-
-# Check package exports
-find packages -name "src/index.ts" -exec echo "=== {} ===" \; -exec cat {} \;
-
-# Check service modules
-find services -name "src/server.ts" -exec echo "=== {} ===" \; -exec cat {} \;
-
-# Count tests (quick)
-pnpm test 2>&1 | tail -5
-
-# Check design tokens
-cat packages/design-tokens/tokens/bytelyst.tokens.json
-ls packages/design-tokens/generated/
-```
-
-### 3. Scan learning_multimodal_memory_agents
-
-```bash
-cd $HOME/code/mygh/learning_multimodal_memory_agents
-
-# Find source files
-find mindlyst-native -maxdepth 3 -name "*.kt" -o -name "*.swift" -o -name "*.tsx" | head -30
-
-# Read key files
-cat AGENTS.md
-cat README.md
-cat ARCHITECTURE.md
-
-# Check dependencies
-cat mindlyst-native/gradle/libs.versions.toml
-cat mindlyst-native/shared/build.gradle.kts
-
-# List shared logic
-ls mindlyst-native/shared/src/commonMain/kotlin/com/mindlyst/shared/
-
-# List platform code
-ls mindlyst-native/iosApp/
-ls mindlyst-native/web/src/pages/
-
-# Check token sync
-head -20 design-system/web/mindlyst.css
-```
-
-## Phase 2: Identify Changes
-
-Compare gathered info against existing docs:
-
-- New packages or services?
-- Changed conventions?
-- New file ownership patterns?
-- Updated environment variables?
-- Different test counts?
-- New CI workflows?
-
-Build a change summary before editing.
-
-## Phase 3: Update Documentation
-
-### 1. Update AGENTS.md (Most Comprehensive)
-
-Ensure these sections are current:
-
-```markdown
-## Project Identity
-
-- Product name, IDs, prefixes
-- License format
-- Config directory
-
-## Monorepo Layout
-
-- Directory tree with descriptions
-- Include sibling repo structure
-- Service ports and responsibilities
-
-## Tech Stack Rules
-
-- Python: version, linter, formatter, tests, logging
-- TypeScript services: framework, patterns, database
-- TypeScript dashboards: framework, shared packages
-
-## Coding Conventions
-
-- MUST follow rules
-- MUST NOT do rules
-- Commit message format
-
-## File Ownership Map
-
-- Table mapping domains → services → key files
-- Include all @bytelyst/\* mappings
-
-## How to Run Things
-
-- Start services command
-- Test commands
-- Docker compose
-- Seed database
-
-## Common Patterns
-
-- Adding Fastify modules
-- Adding dashboard pages
-- Adding service clients
-- Adding backend routes
-- Debugging methodology
-
-## Environment Variables
-
-- Required vars per service
-- Env file locations
-- Azure service references
-
-## Key Documents
-
-- "When you need to..." → "read this" table
-```
-
-### 2. Update CLAUDE.md (Compact Summary)
-
-Keep under 50 lines:
-
-- Identity (product, tech stack)
-- Key commands (start services, run tests)
-- Critical rules (MUST follow)
-- Current @bytelyst/\* wiring state
-
-### 3. Update .cursorrules
-
-```text
-Project: LysnrAI - Voice-to-text platform
-Stack: Python 3.12 + FastAPI + Next.js 16 + Fastify 5
-Rules:
-- Always use req.log, never console.log
-- Every Cosmos doc needs productId field
-- Use @bytelyst/* packages from common_plat
-- Commit: feat(scope): description
-- See AGENTS.md for full details
-```
-
-### 4. Update .github/copilot-instructions.md
-
-```markdown
-# LysnrAI Copilot Instructions
-
-## Always Do
-
-- Use structlog for Python logging
-- Validate with Zod schemas in TypeScript
-- Include productId in all Cosmos documents
-- Use @bytelyst/api-client for service calls
-
-## Never Do
-
-- Use console.log in production
-- Hardcode secrets or API keys
-- Modify tests to make them pass
-- Use any type in TypeScript
-
-## Key Patterns
-
-- Fastify modules: types.ts → repository.ts → routes.ts
-- Dashboard pages: src/app/(dashboard)/page-name/page.tsx
-- Python routes: backend/src/routes/name.py
-
-See AGENTS.md for comprehensive guide.
-```
-
-### 5. Update .windsurfrules
-
-```text
-Project: LysnrAI
-Product ID: lysnrrai
-Config dir: ~/.lysnrai/
-Key services: backend(8000), billing(4002), growth(4001), platform(4003), tracker(4004)
-Dashboards: admin(3001), user(3002), tracker(3003)
-Rules: Use @bytelyst/* packages, no console.log, productId required, commit format: type(scope): desc
-```
-
-### 6. Update .clinerules
-
-```text
-# LysnrAI Project Rules
-- All business logic in backend/src/ or services/
-- Dashboards in admin-dashboard-web/, user-dashboard-web/, tracker-dashboard-web/
-- Shared packages in ../learning_ai_common_plat/packages/
-- Use @bytelyst/cosmos for DB, @bytelyst/auth for JWT
-- Python: use ruff lint, pytest tests
-- TypeScript: use ESLint, Vitest tests
-- Never commit .env files or secrets
-```
-
-### 7. Update .aider.conf.yml
-
-```yaml
-# Aider configuration for LysnrAI
-auto-commits: false
-lint-cmd: |
-  python: ruff check --fix
-  typescript: pnpm lint
-  shell: shellcheck -f gcc
-test-cmd: |
-  python: pytest tests/ -v
-  typescript: pnpm test
-
-# Always include these files in context
-context-files:
-  - AGENTS.md
-  - README_MONO_REPO.md
-  - docker-compose.yml
-  - pyproject.toml
-  - pnpm-workspace.yaml
-  - tsconfig.base.json
-```
-
-### 8. Update .editorconfig
-
-```ini
-# EditorConfig for LysnrAI
-root = true
-
-[*.py]
-indent_style = space
-indent_size = 4
-end_of_line = lf
-charset = utf-8
-trim_trailing_whitespace = true
-
-[*.{js,ts,tsx,json}]
-indent_style = space
-indent_size = 2
-end_of_line = lf
-charset = utf-8
-trim_trailing_whitespace = true
-
-[*.{kt,swift}]
-indent_style = space
-indent_size = 4
-end_of_line = lf
-charset = utf-8
-trim_trailing_whitespace = true
-```
-
-## Phase 4: Validate Updates
-
-```bash
-# For each repo:
-git add .
-git commit -m "docs: update AI agent documentation"
-git push
-
-# Verify files are readable
-cat AGENTS.md | head -20
-cat CLAUDE.md
-cat .cursorrules
-```
-
-## Automation Script
-
-Create `scripts/update-all-agent-docs.sh`:
-
-```bash
-#!/bin/bash
-# Update all agent docs across repos
-
-REPOS=(
-  "$HOME/code/mygh/learning_voice_ai_agent"
-  "$HOME/code/mygh/learning_ai_common_plat"
-  "$HOME/code/mygh/learning_multimodal_memory_agents"
-)
-
-for repo in "${REPOS[@]}"; do
-  echo "Updating docs in $repo"
-  cd "$repo"
-
-  # Run the update workflow
-  # (This would be the full workflow implementation)
-
-  git add .
-  git commit -m "docs: update AI agent documentation"
-  git push
-done
-```
-
-## Notes
-
-- **Be consistent** - Keep the same structure across all repos
-- **Be specific** - Include actual file paths and commands
-- **Stay current** - Run this workflow regularly
-- **Get feedback** - Ask developers if docs are helpful
-- **Version control** - Track changes to understand evolution
-
-## Related Skills
-
-- [Production Readiness](./production-readiness.md) - Docs are part of readiness
-- [Local Development Setup](./local-development.md) - Docs should match local setup
-- [Debug Service](./debug-service.md) - Docs should help with debugging

scripts/update-agent-docs.sh

@@ -519,5 +519,11 @@ if [[ ${#CHANGED_REPOS[@]} -gt 0 ]]; then
     echo "   git -C ${BASE_DIR}/${r} push"
   done
 else
-  ok "All repos already in sync — no changes."
+  if $NO_COMMIT; then
+    ok "Files regenerated. No commits made (--no-commit). Inspect changes with: git -C <repo> status"
+  elif $DRY_RUN; then
+    ok "Dry run complete. Re-run without --dry-run to apply."
+  else
+    ok "All repos already in sync — no changes."
+  fi
 fi