Documentation Standardisation & Unit Test Stabilization

- Overhauled README.md to serve as a unified system index and WIP tracker.
- Standardized documentation filenames (ARCH__, GUIDE__, PLAN__) for better discoverability.
- Archived completed project plans and scopes.
- Fixed regressions in unit tests (errors, models, email) caused by V3 architectural updates.
- Ensured unit tests remain non-destructive and environment-independent via mocking.

documentation/archive/SCOPE__MCP_FIELD_MANAGER.md

@@ -0,0 +1,81 @@
+# Scope: Automated Field Management Tool (MCP)
+
+**Task ID:** 153357623
+**Type:** MCP Tool / Dev Utility
+**Target System:** Aether API V3 (FastAPI + MariaDB)
+
+## 1. Objective
+To create a safe, automated "Vertical Slice" tool that handles the repetitive and error-prone process of adding or modifying fields in the Aether backend.
+
+**Current Manual Process (Pain Points):**
+1.  `ALTER TABLE` in MariaDB (risk of locking or syntax errors).
+2.  Update/Recreate `v_[object]` SQL View (easy to forget, breaks Triple ID).
+3.  Update Pydantic Models in `app/models/` (tedious, risk of schema drift).
+4.  Update `searchable_fields` in `app/object_definitions/` (often forgotten).
+
+## 2. Proposed Solution: `ae_field_manage`
+
+A Python script in the MCP toolset (`agents_sync/scripts/ae_field_manage.py`) that orchestrates these steps atomically.
+
+### Usage Example
+```bash
+# CLI Usage
+python3 ae_field_manage.py add person nickname --type string --length 50 --nullable
+
+# MCP Tool Usage
+{
+  "tool": "ae_field_manage",
+  "action": "add",
+  "object": "person",
+  "field": "nickname",
+  "params": { "type": "string", "length": 50 }
+}
+```
+
+## 3. Implementation Steps
+
+### Phase 1: Analysis & Safety (Dry Run)
+*   [ ] **Input Validation:** Ensure field name is snake_case and valid.
+*   [ ] **Schema Check:** Check if field already exists in DB or Pydantic.
+*   [ ] **Impact Analysis:** Identify which files will be modified (e.g., `app/models/person_models.py`).
+
+### Phase 2: Database Operations
+*   [ ] **Backup:** (Optional) Trigger a quick table dump?
+*   [ ] **DDL Execution:** Run `ALTER TABLE {table} ADD COLUMN {field} {type} ...`.
+*   [ ] **View Recreation:**
+    *   Fetch current view definition OR construct standard V3 view.
+    *   Ensure Triple ID pattern is preserved (`id`, `{type}_id`, `{type}_id_random`).
+    *   Execute `CREATE OR REPLACE VIEW`.
+
+### Phase 3: Codebase Modification (AST/Regex)
+*   [ ] **Pydantic Model Update:**
+    *   Locate `class {Object}_Base(BaseModel):`.
+    *   Inject field definition: `nickname: Optional[str] = Field(None, max_length=50)`.
+    *   Use AST (Abstract Syntax Tree) parsing for safety, or careful Regex if AST is too complex for simple insertions.
+*   [ ] **Search Registry Update:**
+    *   If flag `--searchable` is set, add to `searchable_fields` list in `app/object_definitions/core.py`.
+
+### Phase 4: Verification
+*   [ ] **Integrity Check:** Run `ae_check_integrity` to verify View health.
+*   [ ] **Schema Sync:** Trigger `ae_schema_sync` to update Frontend TS interfaces (if applicable).
+
+## 4. Technical Constraints
+*   **Database:** MariaDB 10.11.
+*   **Language:** Python 3.10+.
+*   **ORM:** SQLAlchemy (for type mapping), but raw SQL for DDL.
+*   **File Paths:** Must respect `~/OSIT_dev/` structure.
+
+## 5. Risks & Mitigation
+*   **Risk:** Corrupting `person_models.py`.
+    *   *Mitigation:* Create a `.bak` copy before writing.
+*   **Risk:** Locking the DB table.
+    *   *Mitigation:* Verify no active heavy transactions (low priority for dev env).
+*   **Risk:** View definition divergence.
+    *   *Mitigation:* The tool should ideally *read* the existing view logic or use a standard template.
+
+## 6. Definition of Done
+*   Can add a string/int/bool field to `person` via one command.
+*   Database column exists.
+*   View `v_person` includes the column.
+*   `Person_Base` model includes the field.
+*   `ae_obj_info person` reflects the change.