[codex] Add Project Instructions governance addendums

docs_build/dev/ProjectInstructions/README.txt

@@ -40,3 +40,7 @@ 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
+- Platform Development Standards: project-instructions/addendums/platform-development-standards.md

project-instructions/addendums/canonical-repository-structure.md

@@ -0,0 +1,78 @@
+# Canonical Repository Structure
+
+## Purpose
+
+Prevent technical debt by requiring all new and modified code to follow one repository structure.
+
+## 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}/
+
+Server:
+- server/{feature-name}/
+
+Tests:
+- tests/toolbox/{tool-name}/
+- tests/engine/{feature-name}/
+- tests/api/{feature-name}/
+- tests/server/{feature-name}/
+- tests/js/shared/
+- tests/regression/
+
+## Rules
+
+- Theme first. Use theme styles whenever possible.
+- Tool CSS is allowed only when a requirement cannot be satisfied by the active theme.
+- Every tool must be independently testable.
+- Regression tests do not replace tool-level tests.
+- Shared functionality belongs in assets/js/shared/.
+- New development must follow the canonical structure.
+- No new scattered JavaScript folders.
+- No new scattered CSS folders.
+- No new scattered test folders.
+
+## Legacy Migration
+
+When a tool is modified:
+
+1. Review JS location.
+2. Review CSS location.
+3. Review test location.
+4. Move touched files into the canonical structure.
+5. Update imports.
+6. Update tests.
+7. Remove legacy references.
+
+Legacy files may only be deleted when no active references remain.
+
+## Folder Ownership
+
+A folder may contain only assets related to that feature.
+
+Example:
+
+assets/toolbox/text-to-speech/
+
+may not contain files used exclusively by another tool.
+
+Shared functionality must be moved to:
+
+assets/js/shared/

project-instructions/addendums/platform-development-standards.md

@@ -0,0 +1,143 @@
+# Platform Development Standards
+
+## Purpose
+
+Establish repository-wide standards for database usage, entity lifecycle management, creator tool design, and shared component reuse.
+
+---
+
+# PostgreSQL Platform Standard
+
+## Rules
+
+- SQLite is deprecated.
+- PostgreSQL is the canonical database platform.
+- New development must not introduce SQLite.
+- New tools must target PostgreSQL.
+- New tests must target PostgreSQL.
+- New migrations must target PostgreSQL.
+
+## Legacy
+
+Existing SQLite references should be removed when touched by active development.
+
+## Exception
+
+Owner approval is required for any non-PostgreSQL database implementation.
+
+---
+
+# Referenced Entity Protection
+
+## Purpose
+
+Prevent accidental data loss and broken references.
+
+## Rules
+
+Entities referenced by another record may not be directly deleted.
+
+Allowed actions:
+
+- Archive
+- Deprecate
+- Replace
+
+Direct deletion is prohibited while references exist.
+
+## Examples
+
+- Messages
+- TTS Profiles
+- Emotion Profiles
+- Characters
+- Objects
+- Assets
+- Worlds
+- Tags
+
+## Exception
+
+Owner approval required for destructive removal.
+
+---
+
+# Table First Tool Standard
+
+## Purpose
+
+Provide a consistent creator experience across all tools.
+
+## Preferred
+
+- Table driven interfaces
+- Inline editing
+- Add row at bottom
+- Expandable child rows
+- Save and Cancel on the active row
+
+## Avoid
+
+- Large data-entry forms
+- Separate edit pages
+- Wizard-style CRUD workflows
+
+## Exception
+
+Forms may be used when table interaction is not practical.
+
+---
+
+# Shared Component Governance
+
+## Purpose
+
+Reduce duplicate code across tools.
+
+## Shared JavaScript Location
+
+```text
+assets/js/shared/
+```
+
+## Examples
+
+- API helpers
+- Table helpers
+- Status helpers
+- Dialog helpers
+- Validation helpers
+
+## Rules
+
+Functionality used by multiple tools should be moved into shared components.
+
+Tool-specific functionality remains within the tool folder.
+
+Shared functionality must not be stored inside an unrelated tool folder.
+
+## Testing
+
+Shared functionality must include tests under:
+
+```text
+tests/js/shared/
+```
+
+Tool-specific functionality remains tested within its corresponding tool test location.
+
+---
+
+# Governance Enforcement
+
+## Rules
+
+New development must follow these standards.
+
+When modifying existing functionality:
+
+1. Review compliance with these standards.
+2. Correct violations when practical within the scope of the work.
+3. Avoid introducing new technical debt.
+
+Repository-wide standards must exist in Project Instructions and not solely within chat discussions.