From 8ceb2bd52352bcdc4c047931fe5cf65633b81a24 Mon Sep 17 00:00:00 2001
From: DavidQ <qbytes.dq@gmail.com>
Date: Mon, 22 Jun 2026 11:53:55 -0400
Subject: [PATCH] PR_26172_OWNER_034-canonical-repository-structure

---
 docs_build/dev/ProjectInstructions/README.txt |  3 ++
 .../canonical-repository-structure.md         | 39 +++++++++++++++++++
 2 files changed, 42 insertions(+)
 create mode 100644 project-instructions/addendums/canonical-repository-structure.md

diff --git a/docs_build/dev/ProjectInstructions/README.txt b/docs_build/dev/ProjectInstructions/README.txt
index 77de19c20..214ab9acb 100644
--- a/docs_build/dev/ProjectInstructions/README.txt
+++ b/docs_build/dev/ProjectInstructions/README.txt
@@ -40,3 +40,6 @@ READ THIS FIRST
 9. Follow OWNER governance decisions.
 10. When guidance conflicts, newest OWNER-approved guidance wins.
 11. Batch Governance Mode is the default for governance, documentation, and administrative work.
+
+Addendum index:
+- Canonical Repository Structure: project-instructions/addendums/canonical-repository-structure.md
diff --git a/project-instructions/addendums/canonical-repository-structure.md b/project-instructions/addendums/canonical-repository-structure.md
new file mode 100644
index 000000000..e26939469
--- /dev/null
+++ b/project-instructions/addendums/canonical-repository-structure.md
@@ -0,0 +1,39 @@
+# Canonical Repository Structure
+
+## Purpose
+
+Establish the canonical repository structure for future development and reduce technical debt.
+
+## Canonical Structure
+
+Tools:
+- toolbox/{tool-name}/index.html
+
+Tool assets:
+- assets/toolbox/{tool-name}/js/index.js
+- assets/toolbox/{tool-name}/css/index.css
+
+Themes:
+- assets/theme-v1/
+- assets/theme-v2/
+
+Shared JavaScript:
+- assets/js/shared/
+
+Engine:
+- src/engine/{feature-name}/
+
+API:
+- api/{feature-name}/
+
+Serverside:
+- serverside/{feature-name}/
+
+## Rules
+
+- Theme first.
+- Tool CSS second.
+- Shared functionality belongs in assets/js/shared/.
+- No new scattered JS folders.
+- No new scattered CSS folders.
+- New development follows the canonical structure.