fix: correct case-sensitive require_once paths and add AGENTS.md (#14)

* fix: correct case-sensitive require_once paths and add AGENTS.md for AI guidance

- Fix includes/plugin.php -> includes/Plugin.php in main plugin file
- Fix includes/core.php -> includes/Core.php in includes/Plugin.php
  (Linux case-sensitive filesystems fail silently on macOS; runtime bug on production)
- Fix .ai-workflows/folder-structure.md: update class files to PascalCase,
  remove references to non-existent admin/ subdirectories (images/, partials/,
  settings/, tools/) that caused read:file_not_found errors in AI sessions
- Add AGENTS.md with authoritative file map to reduce AI agent errors:
  edit:not_read_first, bash:other, edit:edit_stale_read, read:file_not_found

Resolves #13

* fix: markdown formatting in AGENTS.md (Codacy MD022/MD032)

.ai-workflows/folder-structure.md

@@ -16,10 +16,6 @@ This document outlines the folder structure of the plugin and explains the purpo
 
 - **admin/css/** - Admin-specific CSS files
 - **admin/js/** - Admin-specific JavaScript files
-- **admin/images/** - Admin-specific images
-- **admin/partials/** - Admin-specific template partials
-- **admin/settings/** - Admin settings functionality
-- **admin/tools/** - Admin tools functionality
 - **admin/lib/** - Admin-specific library files and helper functions
   - **admin/lib/admin.php** - Admin class for handling admin-specific functionality
   - **admin/lib/modal.php** - Modal class for handling the update source selector modal
@@ -28,13 +24,14 @@ This document outlines the folder structure of the plugin and explains the purpo
 
 The `includes/` directory contains the core plugin functionality:
 
-- **includes/core.php** - Core class for handling the main plugin functionality
+- **includes/Core.php** - Core class for handling the main plugin functionality
-- **includes/plugin.php** - Main plugin class that initializes all components
+- **includes/Plugin.php** - Main plugin class that initializes all components
-- **includes/updater.php** - Updater class for handling plugin updates
+- **includes/Updater.php** - Updater class for handling plugin updates
 
 ## File Naming Conventions
 
-- All PHP files in the `includes/` directory use lowercase filenames
+- PHP class files in the `includes/` directory use PascalCase filenames matching the class name (e.g., `Core.php`, `Plugin.php`, `Updater.php`)
+- PHP files in `admin/lib/` use lowercase filenames (e.g., `admin.php`, `modal.php`)
 - All directories use lowercase names
 - JavaScript and CSS files use kebab-case (e.g., `update-source-selector.js`)
 
@@ -50,10 +47,10 @@ The `includes/` directory contains the core plugin functionality:
 
 When referring to files or directories in AI conversations, use the following format:
 
-- **@includes/plugin.php** - Main plugin class
+- **@includes/Plugin.php** - Main plugin class
-- **@includes/core.php** - Core functionality
+- **@includes/Core.php** - Core functionality
 - **@admin/lib/admin.php** - Admin functionality
 - **@admin/lib/modal.php** - Modal functionality
-- **@includes/updater.php** - Updater functionality
+- **@includes/Updater.php** - Updater functionality
 - **@admin/js/update-source-selector.js** - Update source selector JavaScript
 - **@admin/css/update-source-selector.css** - Update source selector CSS

AGENTS.md

@@ -0,0 +1,101 @@
+# AGENTS.md — AI Agent Guide for wp-fix-plugin-does-not-exist-notices
+
+This file provides precise, verified guidance for AI agents working in this repository. Read it before editing any file to avoid `read:file_not_found` and `edit:not_read_first` errors.
+
+## Repository Purpose
+
+**Fix 'Plugin file does not exist' Notices** — a WordPress plugin that detects active plugins whose files are missing, adds them to the Plugins list with a "Remove Notice" action link, and safely removes their database references.
+
+- GitHub: `wpallstars/wp-fix-plugin-does-not-exist-notices`
+- Namespace: `WPALLSTARS\FixPluginDoesNotExistNotices`
+- Text domain: `wp-fix-plugin-does-not-exist-notices`
+- Current version: see `wp-fix-plugin-does-not-exist-notices.php` header
+
+## Exact File Map (authoritative — verified against git ls-files)
+
+**CRITICAL**: PHP class files in `includes/` use PascalCase. The docs and `require_once` paths must match exactly. On Linux (case-sensitive), wrong case = fatal error.
+
+```
+wp-fix-plugin-does-not-exist-notices.php   # Plugin entry point — sets Version, requires includes/Plugin.php
+includes/Plugin.php                         # Main Plugin class — loads dependencies, inits components
+includes/Core.php                           # Core class — all WordPress hooks and plugin logic
+includes/Updater.php                        # Updater class — handles Git Updater / WP.org update sources
+admin/lib/admin.php                         # Admin\Admin class — admin page rendering, enqueues
+admin/lib/modal.php                         # Admin\Modal class — update source selector modal
+admin/css/admin-styles.css                  # General admin styles
+admin/css/update-source-selector.css        # Styles for the update source modal
+admin/js/admin-scripts.js                   # General admin JS
+admin/js/update-source-selector.js          # JS for the update source modal
+languages/wp-fix-plugin-does-not-exist-notices.pot  # Translation template
+build.sh                                    # Build/release script
+scripts/deploy-local.sh                     # Local deployment helper
+composer.json                               # Composer config (no vendor/ committed)
+README.md                                   # Developer readme
+readme.txt                                  # WordPress.org readme (keep in sync with README.md)
+CHANGELOG.md                                # Changelog (keep in sync with README.md and readme.txt)
+```
+
+**Directories that DO NOT exist** (do not attempt to read or create files here):
+
+- `admin/images/` — does not exist
+- `admin/partials/` — does not exist
+- `admin/settings/` — does not exist
+- `admin/tools/` — does not exist
+- `vendor/` — not committed; loaded at runtime if present
+
+## Before Editing Any File
+
+1. Read the file first: `Read includes/Core.php` — not `includes/core.php` (wrong case fails).
+2. Re-read the file if another tool call may have modified it since your last read.
+3. Verify the file path with `git ls-files '<pattern>'` when uncertain.
+
+## Version Management
+
+Version appears in **four places** — all must be updated together:
+
+1. `wp-fix-plugin-does-not-exist-notices.php` — `Version:` header and `new Plugin(__FILE__, 'X.Y.Z')`
+2. `includes/Plugin.php` — no direct version constant; version passed via constructor
+3. `readme.txt` — `Stable tag:` and changelog section
+4. `CHANGELOG.md` — top entry
+
+`README.md` changelog section must also stay in sync with `CHANGELOG.md`.
+
+## Common Tasks
+
+### Fix a bug in core plugin logic
+
+Edit `includes/Core.php`. All WordPress hooks are registered in the constructor.
+
+### Change admin UI or settings
+
+Edit `admin/lib/admin.php` (Admin class) and/or `admin/lib/modal.php` (Modal class).
+CSS: `admin/css/admin-styles.css` or `admin/css/update-source-selector.css`.
+JS: `admin/js/admin-scripts.js` or `admin/js/update-source-selector.js`.
+
+### Bump version for a release
+
+1. Update version in `wp-fix-plugin-does-not-exist-notices.php` (both header and constructor call).
+2. Update `Stable tag:` in `readme.txt`.
+3. Add changelog entry to `readme.txt`, `CHANGELOG.md`, and `README.md`.
+
+### Add or fix update source logic
+
+Edit `includes/Updater.php`.
+
+## Git Workflow
+
+- Branch naming: `feature/`, `fix/`, `patch/`, `refactor/` prefixes
+- One branch per issue; one PR per issue
+- Push to both `github` and `gitea` remotes
+- Do not include version numbers in branch names during development
+
+## AI Workflow Documentation
+
+Extended guidance is in `.ai-workflows/`:
+
+- `folder-structure.md` — directory layout with correct filenames
+- `git-workflow.md` — branching, commit messages, remote management
+- `feature-development.md` — feature development process
+- `bug-fixing.md` — bug investigation and fix process
+- `release-process.md` — full release checklist including Git Updater notes
+- `dev-prefs-memory.md` — persistent developer preferences

includes/Plugin.php

@@ -110,7 +110,7 @@ class Plugin {
         }
 
         // Load required files
-        require_once $this->plugin_dir . 'includes/core.php';
+        require_once $this->plugin_dir . 'includes/Core.php';
         require_once $this->plugin_dir . 'admin/lib/admin.php';
         require_once $this->plugin_dir . 'admin/lib/modal.php';
     }

wp-fix-plugin-does-not-exist-notices.php

@@ -32,7 +32,7 @@ if (!defined('WPINC')) {
 }
 
 // Load the main plugin class
-require_once plugin_dir_path(__FILE__) . 'includes/plugin.php';
+require_once plugin_dir_path(__FILE__) . 'includes/Plugin.php';
 
 // Initialize the plugin
 // This is a test change for our new workflow