From 75e7ca541a6c38c46a18558591a61dd96e33f0e0 Mon Sep 17 00:00:00 2001 From: Scott Idem Date: Fri, 12 Jun 2026 17:07:03 -0400 Subject: [PATCH] docs: seventh-pass archive unsafe legacy references --- documentation/AE__Architecture.md | 14 ++++---- documentation/AE__Naming_Conventions.md | 17 ++++++---- documentation/AE__Permissions_and_Security.md | 2 +- .../GUIDE__AE_UI_Style_Guidelines.md | 2 +- ...mentation_Refresh_and_Archive_Plan_2026.md | 5 ++- documentation/README__Docs_Index.md | 4 ++- documentation/archive/README.md | 34 +++++++++++++++++++ ...CE__Legacy_Aether_API_Pydantic_Objects.md} | 0 .../REFERENCE__Legacy_Aether_Components.md} | 0 ...FERENCE__Legacy_Aether_Data_Structures.md} | 0 ...FERENCE__Legacy_Performance_Guidelines.md} | 0 ...EFERENCE__Legacy_UI_Component_Patterns.md} | 0 12 files changed, 61 insertions(+), 17 deletions(-) create mode 100644 documentation/archive/README.md rename documentation/{AE__Aether_API_objects.md => archive/REFERENCE__Legacy_Aether_API_Pydantic_Objects.md} (100%) rename documentation/{AE__Components.md => archive/REFERENCE__Legacy_Aether_Components.md} (100%) rename documentation/{AE__Data_Structures.md => archive/REFERENCE__Legacy_Aether_Data_Structures.md} (100%) rename documentation/{AE__Performance_Guidelines.md => archive/REFERENCE__Legacy_Performance_Guidelines.md} (100%) rename documentation/{AE__UI_Component_Patterns.md => archive/REFERENCE__Legacy_UI_Component_Patterns.md} (100%) diff --git a/documentation/AE__Architecture.md b/documentation/AE__Architecture.md index 2fad60e4..52767337 100644 --- a/documentation/AE__Architecture.md +++ b/documentation/AE__Architecture.md @@ -1,5 +1,7 @@ # Aether Project Architecture +**Last Updated:** 2026-06-12 + This document outlines the overall architecture and key technologies used in the Aether SvelteKit frontend project. ## 1. Project Overview @@ -20,7 +22,7 @@ The Aether project is a Svelte and SvelteKit based application, utilizing Tailwi - TipTap (`element_editor_tiptap.svelte`) — WYSIWYG rich-text for content fields (IDAA, Journals, Leads notes) - **Icons:** Lucide Icons (SVG Icons) - **Markdown Parsing:** `marked` library -- **State Management:** Svelte stores, potentially with `liveQuery` from Dexie for reactive IndexedDB interactions. +- **State Management:** Svelte 5 runes plus Dexie `liveQuery`. Events persisted state uses `runed` `PersistedState`; core and IDAA still contain legacy coarse-grained persisted stores pending migration. ### 2.1. Journals as the Canonical Frontend Pattern @@ -78,8 +80,8 @@ Used for client-side persistence of various application states and configuration Used for more structured client-side data storage, often for caching and offline capabilities. -- `ae_core_db`: Core database instance. -- ``: Module-specific database instances. +- `db_core`: Core database instance. +- `db_`: Module-specific database instances (for example, `db_events` and `db_journals`). - ``: Custom module-specific database instances (none currently defined). ## 5. Data Sorting @@ -97,9 +99,9 @@ A set of standardized field names and types are used across Aether objects. These fields are expected to be present in most Aether objects. -- `id`: Primary key for an object (internal use, often a UUID). -- `id_random`: Randomly generated ID for an object (often used for external exposure or URL parameters). -- `_id_random`: Specific random ID for an object (e.g., `person_id_random`). +- `_id`: Canonical randomized string ID returned by V3 (for example, `person_id`). Use this for URLs, relationships, and Dexie indexed lookups. +- `id`: Generic randomized string alias when returned by V3; do not assume it is a DB autonumber. +- `id_random` / `_id_random`: Legacy aliases. Do not introduce new usage. - `code`: Short, unique identifier. - `name`: Display name. - `enable`: Boolean for active/inactive status. diff --git a/documentation/AE__Naming_Conventions.md b/documentation/AE__Naming_Conventions.md index 9d9ce57c..8cb4fcce 100644 --- a/documentation/AE__Naming_Conventions.md +++ b/documentation/AE__Naming_Conventions.md @@ -1,5 +1,7 @@ # Aether Project Naming Conventions +**Last Updated:** 2026-06-12 + ## 1. General Principles - **Clarity:** Names should clearly convey their purpose and meaning. @@ -11,9 +13,10 @@ - **Logic/Service Files:** `ae___.ts` (e.g., `ae_core__account.ts`, `ae_events__event.ts`) - **Database Definition Files:** `db_.ts` (e.g., `db_core.ts`, `db_journals.ts`) -- **Svelte Store Files:** `ae__stores.ts` (e.g., `ae_core_stores.ts`, `ae_journals_stores.ts`) +- **Svelte Store Files:** Follow existing module names. Svelte 5 `PersistedState` files use a `.svelte.ts` suffix and are imported via the `.svelte` module path (for example, `ae_events_stores__badges.svelte.ts`). - **Svelte Components:** - - **Module-specific components:** `ae_comp____.svelte` (e.g., `ae_comp__events__event_card.svelte`) + - **Route-level components:** `ae_comp__.svelte`. + - **Module-specific components:** `ae__comp__.svelte` (for example, `ae_events_comp__session_list.svelte`). - **Generic/reusable components:** `element_.svelte` (e.g., `element_input_file.svelte`, `element_qr_scanner_v2.svelte`) - **SvelteKit Routes:** Follow SvelteKit's standard routing conventions (e.g., `+page.svelte`, `+layout.svelte`, `[id]/+page.svelte`). - **CSS Files:** `ae--.css` (e.g., `ae-c-idaa-light.css`, `ae-osit-default.css`) @@ -37,9 +40,9 @@ - **Singularity:** Use singular nouns for objects and properties (e.g., `example.id`, not `examples.id`). - **IDs:** - - `id`: Primary key for an object (internal use, often a UUID). - - `_id`: Specific ID for an object (e.g., `person_id`). - - `_id_random`: Randomly generated ID for an object (often used for external exposure or URL parameters). + - `_id`: Canonical randomized string ID returned by V3 (for example, `person_id`). + - `id`: Generic randomized string alias when V3 returns one; never assume it is an integer autonumber. + - `_id_random`: Legacy alias; do not introduce new usage. - `account_id`, `site_id`, `user_id`, etc.: Foreign keys. - **Common Properties:** - `code`: Short, unique identifier. @@ -88,6 +91,6 @@ - `` (extended modules) - `` (custom modules) - **IndexedDB:** - - `ae_core_db` - - `` + - `db_core` + - `db_` (for example, `db_events`, `db_journals`) - `` diff --git a/documentation/AE__Permissions_and_Security.md b/documentation/AE__Permissions_and_Security.md index 150532c1..65170d99 100644 --- a/documentation/AE__Permissions_and_Security.md +++ b/documentation/AE__Permissions_and_Security.md @@ -1,6 +1,6 @@ # Aether — Permissions and Security -**Last updated:** 2026-02-27 +**Last Updated:** 2026-02-27 **Source of truth:** `src/lib/ae_utils/ae_utils__perm_checks.ts`, `src/lib/stores/ae_stores.ts` --- diff --git a/documentation/GUIDE__AE_UI_Style_Guidelines.md b/documentation/GUIDE__AE_UI_Style_Guidelines.md index 768e410a..6329b583 100644 --- a/documentation/GUIDE__AE_UI_Style_Guidelines.md +++ b/documentation/GUIDE__AE_UI_Style_Guidelines.md @@ -3,7 +3,7 @@ > **Last Updated:** 2026-03-20 > **Author:** One Sky IT / Scott Idem > **Scope:** All Aether SvelteKit frontend components -> **Related:** `AE__UI_Component_Patterns.md`, `ae-firefly.css`, `documentation/AE__Components.md` +> **Related:** `ae-firefly.css`, `documentation/MODULE__AE_Journals.md`, `documentation/MODULE__AE_Events_Presentation_Management.md` > **Historical implementation log:** `documentation/archive/PROJECT__AE_Style_Review_2026-03.md` --- diff --git a/documentation/PROJECT__Documentation_Refresh_and_Archive_Plan_2026.md b/documentation/PROJECT__Documentation_Refresh_and_Archive_Plan_2026.md index 291d4c14..cd06d608 100644 --- a/documentation/PROJECT__Documentation_Refresh_and_Archive_Plan_2026.md +++ b/documentation/PROJECT__Documentation_Refresh_and_Archive_Plan_2026.md @@ -44,6 +44,9 @@ Do not delete historical context; move to `documentation/archive/` with clear na - Validated all `documentation/*.md` references in active docs; no missing targets remain. - Added ownership and review-trigger metadata to the bootstrap, task list, and docs index. - Reviewed active project docs for archive eligibility. Object Field Editor and Site Passcode Security remain active and were added to the docs index. +- Archived legacy API-object, component-inventory, data-structure, performance, and UI-pattern references that contradicted V3 IDs, Svelte 5, or current private-route execution rules. +- Refreshed `AE__Architecture.md` and `AE__Naming_Conventions.md` as the active replacements. +- Added `documentation/archive/README.md` to explain archive categories and restoration policy. ### Next archive candidates (review + approve) - Older style-review snapshots once current style guide references are centralized. @@ -61,6 +64,6 @@ Monthly lightweight review: ## 5) Immediate Follow-Up Tasks 1. Run a quarterly archive review: identify stale `PROJECT__` docs with no TODO or index linkage and move them to `documentation/archive/`. -2. Review `AE__*` reference docs for overlap, outdated stack assumptions, and inconsistent naming. +2. Review remaining `AE__*` docs (`Permissions`, Docker policy, and UI future ideas) against current source and decide whether each remains active reference or proposal material. 3. Review module docs against current routes and store names rather than relying only on filename/header freshness. 4. Add a lightweight reusable link-check script if manual path validation becomes frequent. diff --git a/documentation/README__Docs_Index.md b/documentation/README__Docs_Index.md index 147d3ff5..c1eee0e1 100644 --- a/documentation/README__Docs_Index.md +++ b/documentation/README__Docs_Index.md @@ -20,6 +20,7 @@ Use this file as the routing map for project documentation. ## 3) Safety and Reference +- `documentation/AE__Architecture.md` - `documentation/AE__Permissions_and_Security.md` - `documentation/REFERENCE__Common_Agent_Mistakes.md` - `documentation/AE__Naming_Conventions.md` @@ -60,6 +61,7 @@ Use this file as the routing map for project documentation. ## 6) Archive -- `documentation/archive/` +- `documentation/archive/README.md` Archive contains completed historical project notes and superseded proposals. +Legacy API-object, component-inventory, data-structure, performance, and UI-pattern snapshots are archived because they describe pre-V3 or pre-runes behavior. Use the active V3, Dexie, style, architecture, and module docs instead. diff --git a/documentation/archive/README.md b/documentation/archive/README.md new file mode 100644 index 00000000..5a6ba8ac --- /dev/null +++ b/documentation/archive/README.md @@ -0,0 +1,34 @@ +# Documentation Archive Index + +This directory preserves completed projects, superseded proposals, historical task logs, and legacy technical references. + +Archived files are not authoritative for current implementation. Start with `documentation/README__Docs_Index.md` and the active module/guides directory. + +## Categories + +### Completed or Superseded Projects + +Files prefixed with `PROJECT__` document completed implementation phases or superseded project plans. + +### Historical Proposals + +Files prefixed with `PROPOSAL__` preserve design ideas that are not the current implementation source. + +### Task History + +Files prefixed with `TODO__Agents__ARCHIVE_` contain completed task history by month. + +### Legacy References + +Files prefixed with `REFERENCE__Legacy_` are retained for historical context but contain pre-V3, pre-runes, or otherwise superseded guidance. + +Do not copy implementation patterns from legacy references without validating them against current source and active guides. + +## Restore Policy + +Move an archived doc back to the active documentation root only when: + +1. Its subject is active again. +2. Its content has been reviewed against current source. +3. Legacy paths, IDs, stores, and API conventions have been updated. +4. It is added to `documentation/README__Docs_Index.md`. diff --git a/documentation/AE__Aether_API_objects.md b/documentation/archive/REFERENCE__Legacy_Aether_API_Pydantic_Objects.md similarity index 100% rename from documentation/AE__Aether_API_objects.md rename to documentation/archive/REFERENCE__Legacy_Aether_API_Pydantic_Objects.md diff --git a/documentation/AE__Components.md b/documentation/archive/REFERENCE__Legacy_Aether_Components.md similarity index 100% rename from documentation/AE__Components.md rename to documentation/archive/REFERENCE__Legacy_Aether_Components.md diff --git a/documentation/AE__Data_Structures.md b/documentation/archive/REFERENCE__Legacy_Aether_Data_Structures.md similarity index 100% rename from documentation/AE__Data_Structures.md rename to documentation/archive/REFERENCE__Legacy_Aether_Data_Structures.md diff --git a/documentation/AE__Performance_Guidelines.md b/documentation/archive/REFERENCE__Legacy_Performance_Guidelines.md similarity index 100% rename from documentation/AE__Performance_Guidelines.md rename to documentation/archive/REFERENCE__Legacy_Performance_Guidelines.md diff --git a/documentation/AE__UI_Component_Patterns.md b/documentation/archive/REFERENCE__Legacy_UI_Component_Patterns.md similarity index 100% rename from documentation/AE__UI_Component_Patterns.md rename to documentation/archive/REFERENCE__Legacy_UI_Component_Patterns.md