From 24dfac410dcd46f4ed93ee75ed0ef9d10d00908f Mon Sep 17 00:00:00 2001
From: objecttothis <17935339+objecttothis@users.noreply.github.com>
Date: Tue, 15 Sep 2026 12:06:56 +0400
Subject: [PATCH] docs: document core/plugin boundary rules

Add explicit guidance in AGENTS.md and app/Plugins/README.md
stating core code must never reference a specific plugin.

- Clarify no plugin name/path may appear in composer.json,
  package.json, app/Config/*, or other core files
- State plugins resolve solely via PSR-4 autoloading and
  PluginManager runtime auto-discovery
- Note installing/removing a plugin must never require
  editing files outside app/Plugins/<PluginName>/

Signed-off-by: objecttothis <17935339+objecttothis@users.noreply.github.com>
---
 AGENTS.md             | 7 +++++++
 app/Plugins/README.md | 7 +++++++
 2 files changed, 14 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index f9f2ff737..5e721855d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -87,6 +87,13 @@ Plugins live in `app/Plugins/<PluginName>/` and are auto-discovered by `PluginMa
 - Configuration stored in `ospos_plugin_config` table
 - Plugin-specific routes go in `Config/Routes.php` within the plugin directory
 
+#### Core/Plugin Boundary
+
+Core must never reference a specific plugin by name or path:
+- No plugin name may appear in `composer.json`, `package.json`, `app/Config/*`, or any other core file
+- Plugins resolve entirely through PSR-4 autoloading (`App\Plugins\{Name}\...` → `app/Plugins/{Name}/...`) and runtime auto-discovery via `PluginManager`
+- Installing or removing a plugin must never require editing a core file
+
 #### View Hook Points
 
 Core views inject plugin UI using `pluginContent('hook_name', $data)`. All currently defined hook points are listed in `app/Plugins/README.md`. When adding a new hook point to a core view:
diff --git a/app/Plugins/README.md b/app/Plugins/README.md
index f799557b0..a055fe0ed 100644
--- a/app/Plugins/README.md
+++ b/app/Plugins/README.md
@@ -26,6 +26,13 @@ The PluginManager recursively scans `app/Plugins/` directory:
 
 Both formats are supported, but directory plugins allow for self-contained packages with their own components.
 
+### Core/Plugin Boundary
+
+Core never references a specific plugin:
+- Installing or removing a plugin must never require editing any file outside `app/Plugins/<PluginName>/`
+- No plugin name or path may appear in `composer.json`, `package.json`, `app/Config/*`, or any other core file
+- Everything resolves via PSR-4 autoloading and runtime auto-discovery
+
 ## Uninstall
 
 > **Warning:** Uninstall is destructive and cannot be reversed. All plugin data will be permanently deleted.