From 190114d043a1a8d90ec39918dcb86263621a7169 Mon Sep 17 00:00:00 2001 From: Alexander Sullivan Date: Wed, 7 Jan 2026 21:32:09 +0000 Subject: [PATCH 1/8] maybe --- .github/prompts/audit-docs.prompt.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/.github/prompts/audit-docs.prompt.md b/.github/prompts/audit-docs.prompt.md index 11b913e..e5dc08b 100644 --- a/.github/prompts/audit-docs.prompt.md +++ b/.github/prompts/audit-docs.prompt.md @@ -41,10 +41,17 @@ Execute **Phase 1** and **Phase 2** in order. - **Task:** - Update outdated info, fix inaccuracies, and improve overall quality/clarity. - Consolidate fragmented files to reduce noise. - - **Create New Files & Directories (Strategic Expansion):** You are authorized and encouraged to create new artifacts, but only when strictly necessary. - - **New Components:** If a new system component or module exists and does not logically fit into any existing file, create a new one. - - **External APIs/Tools:** If a new feature is explicitly meant for external use, create a dedicated usage guide. - - **Missing Structures:** If a standard directory is missing but needed to properly organize the new documentation, create it. + - **Create New Files & Directories (Strategic Expansion):** + - **Step 1: Check Existing Structure.** Before creating anything, scan `docs/`. If a logical home exists, place the file there. + - **Step 2: Apply Diátaxis Framework.** If a **NEW** directory is required, or the content is a distinct new system, organize it using the **Diátaxis** structure: + - _Tutorials_ (Learning-oriented) + - _How-To Guides_ (Problem-oriented) + - _Reference_ (Information-oriented) + - _Explanation_ (Understanding-oriented) + - **Scope:** Create new artifacts for: + - **New Components:** Systems, designs, modules or architecture that do not fit into existing files. + - **External APIs:** Dedicated usage guides for external consumers. + - **Missing Structures:** Standard directories needed for organization. - **Next:** Proceed to Phase 3 **ONLY** if Phase 1 and Phase 2 resulted in **ZERO** updates. 3. **Phase 3: Fallback Cleanup (Conditional)** @@ -96,6 +103,7 @@ Execute **Phase 1** and **Phase 2** in order. - **High-Density, Low-Volume:** - Avoid "Wall of Text." Use bullet points and headers to break up density. - Do not narrate code line-by-line. Explain _why_ it exists and _how_ the system uses it. + - **Zero Bloat:** If a sentence does not add strict technical value or learning clarity, do not add it. --- @@ -139,12 +147,13 @@ Execute **Phase 1** and **Phase 2** in order. 1. **Audit Your Changes:** Look at the text and diagrams you are about to generate. 2. **Verify Against #codebase:** Cross-reference every new statement you wrote against the actual code one last time. -3. **Check for Accuracy:** +3. **Check for Accuracy & Bloat:** - _Did I hallucinate a function name or function logic?_ - _Is this path correct?_ - _Does this diagram match the actual logic flow?_ - _Are my statements 100% verifiable and grounded in existing #codebase implementation?_ -4. **Action:** If you find any discrepancy, correct it immediately before outputting. + - _Did I write unnecessary fluff? If yes, delete it._ +4. **Action:** If you find any discrepancy or bloat, correct it immediately before outputting. --- @@ -158,3 +167,4 @@ Before concluding this task, verify: 4. _Are my diagrams strictly based on current #codebase (no styling)?_ 5. _Did I place implementation citations at the end of sections?_ 6. _Did I run Phase 2 (General Audit) even if I made changes in Phase 1?_ +7. _Did I follow the Diátaxis Framework for any NEW directory structures?_ From a0db6ed0073ecca3f9945052d0642a65fba635bb Mon Sep 17 00:00:00 2001 From: Alexander Sullivan Date: Thu, 8 Jan 2026 15:21:18 +0000 Subject: [PATCH 2/8] update again --- .github/prompts/audit-docs.prompt.md | 51 +++++++++++++++------------- 1 file changed, 27 insertions(+), 24 deletions(-) diff --git a/.github/prompts/audit-docs.prompt.md b/.github/prompts/audit-docs.prompt.md index e5dc08b..6a2ea5a 100644 --- a/.github/prompts/audit-docs.prompt.md +++ b/.github/prompts/audit-docs.prompt.md @@ -2,12 +2,12 @@ title: 'Audit and Update docs/ Directory' scope: 'repo' targets: - - #file:docs - - #codebase + - #file:docs + - #codebase labels: - - 'documentation' - - 'audit' - - 'maintenance' + - 'documentation' + - 'audit' + - 'maintenance' --- ## Role & Purpose @@ -94,11 +94,11 @@ Execute **Phase 1** and **Phase 2** in order. - **Subsequent Mentions:** Use only the acronym. - _Example:_ "...therefore the CPU optimizes the load." -- **File Citations (End-of-Section):** - - Do not break the reading flow with inline citations (like scientific papers). - - Place links to the source code at the very end of the specific section or paragraph. +- **Mandatory File Citations (The "Proof of Work" Rule):** + - **Strict Requirement:** You are forbidden from describing technical logic without citing the source file. + - **Placement:** Do not break the reading flow with inline citations. Place links at the very end of the specific section or paragraph. - **Format:** `Implementation: [filename](./path/to/file)` - - **Rule:** All referenced files **MUST** be hyperlinked. + - **Enforcement:** If you cannot find the file to link, **delete the text**. You may not write about code you cannot link to. - **High-Density, Low-Volume:** - Avoid "Wall of Text." Use bullet points and headers to break up density. @@ -107,22 +107,24 @@ Execute **Phase 1** and **Phase 2** in order. --- -## 4. Visual Diagrams +## 4. Mermaid/Visual Diagrams (Strategic & Meaningful) -**Goal:** Use diagrams to simplify complexity. A picture is worth a thousand words. +**Goal:** Proactively use **Mermaid** diagrams to visualize complexity. A picture is worth a thousand words. -**When to Use (High Value):** +**The "Complexity Threshold" (When to Create):** +If you are documenting the following categories, a **Mermaid** diagram is **strongly expected**: +- **System Interactions:** Multi-service communication. +- **State Management:** Complex lifecycles, State machines, or Workflow engines. +- **Data Architecture:** Data ingestion pipelines or Event-driven architectures. +- **Logic depth:** If a process involves more than 5 distinct steps or components interacting, create a diagram. -- **Complex Concepts:** Data flows, component interactions, state lifecycles, and architectural overviews. -- **Visual Aid:** If a concept is difficult to explain in text, create a diagram. - -**When NOT to Use (Low Value):** - -- **Trivial Logic:** Do not diagram simple, linear functions or basic CRUD operations. -- **Over-diagramming:** Do not create a diagram for every single file. Use them strategically where complexity exists. +**When NOT to Create:** +- **Trivial Logic:** Simple function calls, basic CRUD, or single-file utility functions. +- **Redundancy:** Do not create diagrams that simply repeat a bulleted list of a few items. +- **Overuse:** Avoid diagrams for every minor detail. Use only when it adds clarity. **Technical Rules:** - +- **Format:** All diagrams must be written in valid **Mermaid** syntax. No ASCII art or static images. - **Accessibility:** Do **NOT** use Mermaid `style` or color customizations. Keep default and clean. - **Accuracy:** Diagrams must reflect **actual, current code**. No hypothetical structures. - **Types:** Prefer `flowchart`, `sequenceDiagram`, `classDiagram`, `stateDiagram`. @@ -147,13 +149,14 @@ Execute **Phase 1** and **Phase 2** in order. 1. **Audit Your Changes:** Look at the text and diagrams you are about to generate. 2. **Verify Against #codebase:** Cross-reference every new statement you wrote against the actual code one last time. -3. **Check for Accuracy & Bloat:** +3. **Check for Accuracy, Bloat, & Visuals:** - _Did I hallucinate a function name or function logic?_ - _Is this path correct?_ - - _Does this diagram match the actual logic flow?_ - _Are my statements 100% verifiable and grounded in existing #codebase implementation?_ - _Did I write unnecessary fluff? If yes, delete it._ -4. **Action:** If you find any discrepancy or bloat, correct it immediately before outputting. + - **_Did I describe a complex flow (like a Data Flow or Architecture) but skip the Mermaid diagram? If yes, go back and add it._** + - _Did I cite the file for the logic I just explained? If not, find the file or delete the text._ +4. **Action:** If you find any discrepancy, missing citation/diagram, or bloat, correct it immediately before outputting. --- @@ -164,7 +167,7 @@ Before concluding this task, verify: 1. _Does this content serve both internal and external devs?_ 2. _Did I remove all placeholders?_ 3. _Did I properly define all acronyms on first use?_ -4. _Are my diagrams strictly based on current #codebase (no styling)?_ +4. _Did I include meaningful Mermaid diagrams for complex systems?_ 5. _Did I place implementation citations at the end of sections?_ 6. _Did I run Phase 2 (General Audit) even if I made changes in Phase 1?_ 7. _Did I follow the Diátaxis Framework for any NEW directory structures?_ From ba15a01a8434119ca71285e082bc7a5b64eb8316 Mon Sep 17 00:00:00 2001 From: Alexander Sullivan Date: Thu, 8 Jan 2026 10:43:06 -0500 Subject: [PATCH 3/8] re-ran prettier --- .github/prompts/audit-docs.prompt.md | 13 +- package-lock.json | 189 +++++++++++++++------------ package.json | 12 +- 3 files changed, 116 insertions(+), 98 deletions(-) diff --git a/.github/prompts/audit-docs.prompt.md b/.github/prompts/audit-docs.prompt.md index 6a2ea5a..430408f 100644 --- a/.github/prompts/audit-docs.prompt.md +++ b/.github/prompts/audit-docs.prompt.md @@ -2,12 +2,12 @@ title: 'Audit and Update docs/ Directory' scope: 'repo' targets: - - #file:docs - - #codebase + - #file:docs + - #codebase labels: - - 'documentation' - - 'audit' - - 'maintenance' + - 'documentation' + - 'audit' + - 'maintenance' --- ## Role & Purpose @@ -113,17 +113,20 @@ Execute **Phase 1** and **Phase 2** in order. **The "Complexity Threshold" (When to Create):** If you are documenting the following categories, a **Mermaid** diagram is **strongly expected**: + - **System Interactions:** Multi-service communication. - **State Management:** Complex lifecycles, State machines, or Workflow engines. - **Data Architecture:** Data ingestion pipelines or Event-driven architectures. - **Logic depth:** If a process involves more than 5 distinct steps or components interacting, create a diagram. **When NOT to Create:** + - **Trivial Logic:** Simple function calls, basic CRUD, or single-file utility functions. - **Redundancy:** Do not create diagrams that simply repeat a bulleted list of a few items. - **Overuse:** Avoid diagrams for every minor detail. Use only when it adds clarity. **Technical Rules:** + - **Format:** All diagrams must be written in valid **Mermaid** syntax. No ASCII art or static images. - **Accessibility:** Do **NOT** use Mermaid `style` or color customizations. Keep default and clean. - **Accuracy:** Diagrams must reflect **actual, current code**. No hypothetical structures. diff --git a/package-lock.json b/package-lock.json index 2db6a74..24e0fd8 100644 --- a/package-lock.json +++ b/package-lock.json @@ -10,8 +10,8 @@ "dependencies": { "@emotion/react": "^11.14.0", "@emotion/styled": "^11.14.1", - "@mui/icons-material": "^7.3.6", - "@mui/material": "^7.3.6", + "@mui/icons-material": "^7.3.7", + "@mui/material": "^7.3.7", "@sentry/integrations": "^7.114.0", "@sentry/nextjs": "^10.32.1", "@vercel/speed-insights": "^1.3.1", @@ -29,19 +29,19 @@ "@svgr/webpack": "^8.1.0", "@testing-library/jest-dom": "^6.9.1", "@testing-library/react": "^16.3.1", - "@trivago/prettier-plugin-sort-imports": "^6.0.1", + "@trivago/prettier-plugin-sort-imports": "^6.0.2", "@types/jest": "^30.0.0", "@types/lodash": "^4.17.21", "@types/node": "^25.0.3", "@types/react": "^19.2.7", "@types/react-dom": "^19.2.3", - "caniuse-lite": "^1.0.30001762", + "caniuse-lite": "^1.0.30001763", "concurrently": "^9.2.1", - "cypress": "^15.8.1", + "cypress": "^15.8.2", "cypress-axe": "^1.7.0", "eslint": "^9.39.2", "eslint-config-prettier": "^10.1.8", - "eslint-plugin-cypress": "^5.2.0", + "eslint-plugin-cypress": "^5.2.1", "eslint-plugin-prettier": "^5.5.4", "eslint-plugin-react": "^7.37.5", "eslint-plugin-react-hooks": "^7.0.1", @@ -4476,9 +4476,9 @@ } }, "node_modules/@mui/core-downloads-tracker": { - "version": "7.3.6", - "resolved": "https://registry.npmjs.org/@mui/core-downloads-tracker/-/core-downloads-tracker-7.3.6.tgz", - "integrity": "sha512-QaYtTHlr8kDFN5mE1wbvVARRKH7Fdw1ZuOjBJcFdVpfNfRYKF3QLT4rt+WaB6CKJvpqxRsmEo0kpYinhH5GeHg==", + "version": "7.3.7", + "resolved": "https://registry.npmjs.org/@mui/core-downloads-tracker/-/core-downloads-tracker-7.3.7.tgz", + "integrity": "sha512-8jWwS6FweMkpyRkrJooamUGe1CQfO1yJ+lM43IyUJbrhHW/ObES+6ry4vfGi8EKaldHL3t3BG1bcLcERuJPcjg==", "license": "MIT", "funding": { "type": "opencollective", @@ -4486,9 +4486,9 @@ } }, "node_modules/@mui/icons-material": { - "version": "7.3.6", - "resolved": "https://registry.npmjs.org/@mui/icons-material/-/icons-material-7.3.6.tgz", - "integrity": "sha512-0FfkXEj22ysIq5pa41A2NbcAhJSvmcZQ/vcTIbjDsd6hlslG82k5BEBqqS0ZJprxwIL3B45qpJ+bPHwJPlF7uQ==", + "version": "7.3.7", + "resolved": "https://registry.npmjs.org/@mui/icons-material/-/icons-material-7.3.7.tgz", + "integrity": "sha512-3Q+ulAqG+A1+R4ebgoIs7AccaJhIGy+Xi/9OnvX376jQ6wcy+rz4geDGrxQxCGzdjOQr4Z3NgyFSZCz4T999lA==", "license": "MIT", "dependencies": { "@babel/runtime": "^7.28.4" @@ -4501,7 +4501,7 @@ "url": "https://opencollective.com/mui-org" }, "peerDependencies": { - "@mui/material": "^7.3.6", + "@mui/material": "^7.3.7", "@types/react": "^17.0.0 || ^18.0.0 || ^19.0.0", "react": "^17.0.0 || ^18.0.0 || ^19.0.0" }, @@ -4512,23 +4512,23 @@ } }, "node_modules/@mui/material": { - "version": "7.3.6", - "resolved": "https://registry.npmjs.org/@mui/material/-/material-7.3.6.tgz", - "integrity": "sha512-R4DaYF3dgCQCUAkr4wW1w26GHXcf5rCmBRHVBuuvJvaGLmZdD8EjatP80Nz5JCw0KxORAzwftnHzXVnjR8HnFw==", + "version": "7.3.7", + "resolved": "https://registry.npmjs.org/@mui/material/-/material-7.3.7.tgz", + "integrity": "sha512-6bdIxqzeOtBAj2wAsfhWCYyMKPLkRO9u/2o5yexcL0C3APqyy91iGSWgT3H7hg+zR2XgE61+WAu12wXPON8b6A==", "license": "MIT", "peer": true, "dependencies": { "@babel/runtime": "^7.28.4", - "@mui/core-downloads-tracker": "^7.3.6", - "@mui/system": "^7.3.6", - "@mui/types": "^7.4.9", - "@mui/utils": "^7.3.6", + "@mui/core-downloads-tracker": "^7.3.7", + "@mui/system": "^7.3.7", + "@mui/types": "^7.4.10", + "@mui/utils": "^7.3.7", "@popperjs/core": "^2.11.8", "@types/react-transition-group": "^4.4.12", "clsx": "^2.1.1", - "csstype": "^3.1.3", + "csstype": "^3.2.3", "prop-types": "^15.8.1", - "react-is": "^19.2.0", + "react-is": "^19.2.3", "react-transition-group": "^4.4.5" }, "engines": { @@ -4541,7 +4541,7 @@ "peerDependencies": { "@emotion/react": "^11.5.0", "@emotion/styled": "^11.3.0", - "@mui/material-pigment-css": "^7.3.6", + "@mui/material-pigment-css": "^7.3.7", "@types/react": "^17.0.0 || ^18.0.0 || ^19.0.0", "react": "^17.0.0 || ^18.0.0 || ^19.0.0", "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0" @@ -4562,13 +4562,13 @@ } }, "node_modules/@mui/private-theming": { - "version": "7.3.6", - "resolved": "https://registry.npmjs.org/@mui/private-theming/-/private-theming-7.3.6.tgz", - "integrity": "sha512-Ws9wZpqM+FlnbZXaY/7yvyvWQo1+02Tbx50mVdNmzWEi51C51y56KAbaDCYyulOOBL6BJxuaqG8rNNuj7ivVyw==", + "version": "7.3.7", + "resolved": "https://registry.npmjs.org/@mui/private-theming/-/private-theming-7.3.7.tgz", + "integrity": "sha512-w7r1+CYhG0syCAQUWAuV5zSaU2/67WA9JXUderdb7DzCIJdp/5RmJv6L85wRjgKCMsxFF0Kfn0kPgPbPgw/jdw==", "license": "MIT", "dependencies": { "@babel/runtime": "^7.28.4", - "@mui/utils": "^7.3.6", + "@mui/utils": "^7.3.7", "prop-types": "^15.8.1" }, "engines": { @@ -4589,16 +4589,16 @@ } }, "node_modules/@mui/styled-engine": { - "version": "7.3.6", - "resolved": "https://registry.npmjs.org/@mui/styled-engine/-/styled-engine-7.3.6.tgz", - "integrity": "sha512-+wiYbtvj+zyUkmDB+ysH6zRjuQIJ+CM56w0fEXV+VDNdvOuSywG+/8kpjddvvlfMLsaWdQe5oTuYGBcodmqGzQ==", + "version": "7.3.7", + "resolved": "https://registry.npmjs.org/@mui/styled-engine/-/styled-engine-7.3.7.tgz", + "integrity": "sha512-y/QkNXv6cF6dZ5APztd/dFWfQ6LHKPx3skyYO38YhQD4+Cxd6sFAL3Z38WMSSC8LQz145Mpp3CcLrSCLKPwYAg==", "license": "MIT", "dependencies": { "@babel/runtime": "^7.28.4", "@emotion/cache": "^11.14.0", "@emotion/serialize": "^1.3.3", "@emotion/sheet": "^1.4.0", - "csstype": "^3.1.3", + "csstype": "^3.2.3", "prop-types": "^15.8.1" }, "engines": { @@ -4623,18 +4623,18 @@ } }, "node_modules/@mui/system": { - "version": "7.3.6", - "resolved": "https://registry.npmjs.org/@mui/system/-/system-7.3.6.tgz", - "integrity": "sha512-8fehAazkHNP1imMrdD2m2hbA9sl7Ur6jfuNweh5o4l9YPty4iaZzRXqYvBCWQNwFaSHmMEj2KPbyXGp7Bt73Rg==", + "version": "7.3.7", + "resolved": "https://registry.npmjs.org/@mui/system/-/system-7.3.7.tgz", + "integrity": "sha512-DovL3k+FBRKnhmatzUMyO5bKkhMLlQ9L7Qw5qHrre3m8zCZmE+31NDVBFfqrbrA7sq681qaEIHdkWD5nmiAjyQ==", "license": "MIT", "dependencies": { "@babel/runtime": "^7.28.4", - "@mui/private-theming": "^7.3.6", - "@mui/styled-engine": "^7.3.6", - "@mui/types": "^7.4.9", - "@mui/utils": "^7.3.6", + "@mui/private-theming": "^7.3.7", + "@mui/styled-engine": "^7.3.7", + "@mui/types": "^7.4.10", + "@mui/utils": "^7.3.7", "clsx": "^2.1.1", - "csstype": "^3.1.3", + "csstype": "^3.2.3", "prop-types": "^15.8.1" }, "engines": { @@ -4663,9 +4663,9 @@ } }, "node_modules/@mui/types": { - "version": "7.4.9", - "resolved": "https://registry.npmjs.org/@mui/types/-/types-7.4.9.tgz", - "integrity": "sha512-dNO8Z9T2cujkSIaCnWwprfeKmTWh97cnjkgmpFJ2sbfXLx8SMZijCYHOtP/y5nnUb/Rm2omxbDMmtUoSaUtKaw==", + "version": "7.4.10", + "resolved": "https://registry.npmjs.org/@mui/types/-/types-7.4.10.tgz", + "integrity": "sha512-0+4mSjknSu218GW3isRqoxKRTOrTLd/vHi/7UC4+wZcUrOAqD9kRk7UQRL1mcrzqRoe7s3UT6rsRpbLkW5mHpQ==", "license": "MIT", "dependencies": { "@babel/runtime": "^7.28.4" @@ -4680,17 +4680,17 @@ } }, "node_modules/@mui/utils": { - "version": "7.3.6", - "resolved": "https://registry.npmjs.org/@mui/utils/-/utils-7.3.6.tgz", - "integrity": "sha512-jn+Ba02O6PiFs7nKva8R2aJJ9kJC+3kQ2R0BbKNY3KQQ36Qng98GnPRFTlbwYTdMD6hLEBKaMLUktyg/rTfd2w==", + "version": "7.3.7", + "resolved": "https://registry.npmjs.org/@mui/utils/-/utils-7.3.7.tgz", + "integrity": "sha512-+YjnjMRnyeTkWnspzoxRdiSOgkrcpTikhNPoxOZW0APXx+urHtUoXJ9lbtCZRCA5a4dg5gSbd19alL1DvRs5fg==", "license": "MIT", "dependencies": { "@babel/runtime": "^7.28.4", - "@mui/types": "^7.4.9", + "@mui/types": "^7.4.10", "@types/prop-types": "^15.7.15", "clsx": "^2.1.1", "prop-types": "^15.8.1", - "react-is": "^19.2.0" + "react-is": "^19.2.3" }, "engines": { "node": ">=14.0.0" @@ -4879,9 +4879,9 @@ } }, "node_modules/@opentelemetry/context-async-hooks": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/@opentelemetry/context-async-hooks/-/context-async-hooks-2.2.0.tgz", - "integrity": "sha512-qRkLWiUEZNAmYapZ7KGS5C4OmBLcP/H2foXeOEaowYCR0wi89fHejrfYfbuLVCMLp/dWZXKvQusdbUEZjERfwQ==", + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/context-async-hooks/-/context-async-hooks-2.3.0.tgz", + "integrity": "sha512-hGcsT0qDP7Il1L+qT3JFpiGl1dCjF794Bb4yCRCYdr7XC0NwHtOF3ngF86Gk6TUnsakbyQsDQ0E/S4CU0F4d4g==", "license": "Apache-2.0", "peer": true, "engines": { @@ -4892,9 +4892,9 @@ } }, "node_modules/@opentelemetry/core": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/@opentelemetry/core/-/core-2.2.0.tgz", - "integrity": "sha512-FuabnnUm8LflnieVxs6eP7Z383hgQU4W1e3KJS6aOG3RxWxcHyBxH8fDMHNgu/gFx/M2jvTOW/4/PHhLz6bjWw==", + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/core/-/core-2.3.0.tgz", + "integrity": "sha512-PcmxJQzs31cfD0R2dE91YGFcLxOSN4Bxz7gez5UwSUjCai8BwH/GI5HchfVshHkWdTkUs0qcaPJgVHKXUp7I3A==", "license": "Apache-2.0", "peer": true, "dependencies": { @@ -5072,6 +5072,21 @@ "@opentelemetry/api": "^1.3.0" } }, + "node_modules/@opentelemetry/instrumentation-http/node_modules/@opentelemetry/core": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/core/-/core-2.2.0.tgz", + "integrity": "sha512-FuabnnUm8LflnieVxs6eP7Z383hgQU4W1e3KJS6aOG3RxWxcHyBxH8fDMHNgu/gFx/M2jvTOW/4/PHhLz6bjWw==", + "license": "Apache-2.0", + "dependencies": { + "@opentelemetry/semantic-conventions": "^1.29.0" + }, + "engines": { + "node": "^18.19.0 || >=20.6.0" + }, + "peerDependencies": { + "@opentelemetry/api": ">=1.0.0 <1.10.0" + } + }, "node_modules/@opentelemetry/instrumentation-ioredis": { "version": "0.56.0", "resolved": "https://registry.npmjs.org/@opentelemetry/instrumentation-ioredis/-/instrumentation-ioredis-0.56.0.tgz", @@ -5296,13 +5311,13 @@ } }, "node_modules/@opentelemetry/resources": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/@opentelemetry/resources/-/resources-2.2.0.tgz", - "integrity": "sha512-1pNQf/JazQTMA0BiO5NINUzH0cbLbbl7mntLa4aJNmCCXSj0q03T5ZXXL0zw4G55TjdL9Tz32cznGClf+8zr5A==", + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/resources/-/resources-2.3.0.tgz", + "integrity": "sha512-shlr2l5g+87J8wqYlsLyaUsgKVRO7RtX70Ckd5CtDOWtImZgaUDmf4Z2ozuSKQLM2wPDR0TE/3bPVBNJtRm/cQ==", "license": "Apache-2.0", "peer": true, "dependencies": { - "@opentelemetry/core": "2.2.0", + "@opentelemetry/core": "2.3.0", "@opentelemetry/semantic-conventions": "^1.29.0" }, "engines": { @@ -5313,14 +5328,14 @@ } }, "node_modules/@opentelemetry/sdk-trace-base": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/@opentelemetry/sdk-trace-base/-/sdk-trace-base-2.2.0.tgz", - "integrity": "sha512-xWQgL0Bmctsalg6PaXExmzdedSp3gyKV8mQBwK/j9VGdCDu2fmXIb2gAehBKbkXCpJ4HPkgv3QfoJWRT4dHWbw==", + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@opentelemetry/sdk-trace-base/-/sdk-trace-base-2.3.0.tgz", + "integrity": "sha512-B0TQ2e9h0ETjpI+eGmCz8Ojb+lnYms0SE3jFwEKrN/PK4aSVHU28AAmnOoBmfub+I3jfgPwvDJgomBA5a7QehQ==", "license": "Apache-2.0", "peer": true, "dependencies": { - "@opentelemetry/core": "2.2.0", - "@opentelemetry/resources": "2.2.0", + "@opentelemetry/core": "2.3.0", + "@opentelemetry/resources": "2.3.0", "@opentelemetry/semantic-conventions": "^1.29.0" }, "engines": { @@ -6664,9 +6679,9 @@ } }, "node_modules/@sinclair/typebox": { - "version": "0.34.46", - "resolved": "https://registry.npmjs.org/@sinclair/typebox/-/typebox-0.34.46.tgz", - "integrity": "sha512-kiW7CtS/NkdvTUjkjUJo7d5JsFfbJ14YjdhDk9KoEgK6nFjKNXZPrX0jfLA8ZlET4cFLHxOZ/0vFKOP+bOxIOQ==", + "version": "0.34.47", + "resolved": "https://registry.npmjs.org/@sinclair/typebox/-/typebox-0.34.47.tgz", + "integrity": "sha512-ZGIBQ+XDvO5JQku9wmwtabcVTHJsgSWAHYtVuM9pBNNR5E88v6Jcj/llpmsjivig5X8A8HHOb4/mbEKPS5EvAw==", "dev": true, "license": "MIT" }, @@ -7055,9 +7070,9 @@ } }, "node_modules/@trivago/prettier-plugin-sort-imports": { - "version": "6.0.1", - "resolved": "https://registry.npmjs.org/@trivago/prettier-plugin-sort-imports/-/prettier-plugin-sort-imports-6.0.1.tgz", - "integrity": "sha512-6B13DCWDfAfh4AEJ43gRgeCSAQmlKG5LHqHzHc0lbUwgBy0rX7o41US+46Fd4XiXBx+JDGEz3NBadCbUls0dUQ==", + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/@trivago/prettier-plugin-sort-imports/-/prettier-plugin-sort-imports-6.0.2.tgz", + "integrity": "sha512-3DgfkukFyC/sE/VuYjaUUWoFfuVjPK55vOFDsxD56XXynFMCZDYFogH2l/hDfOsQAm1myoU/1xByJ3tWqtulXA==", "dev": true, "license": "Apache-2.0", "dependencies": { @@ -8440,9 +8455,9 @@ "license": "MIT" }, "node_modules/axe-core": { - "version": "4.11.0", - "resolved": "https://registry.npmjs.org/axe-core/-/axe-core-4.11.0.tgz", - "integrity": "sha512-ilYanEU8vxxBexpJd8cWM4ElSQq4QctCLKih0TSfjIfCQTeyH/6zVrmIJfLPrKTKJRbiG+cfnZbQIjAlJmF1jQ==", + "version": "4.11.1", + "resolved": "https://registry.npmjs.org/axe-core/-/axe-core-4.11.1.tgz", + "integrity": "sha512-BASOg+YwO2C+346x3LZOeoovTIoTrRqEsqMa6fmfAV0P+U9mFr9NsyOEpiYvFjbc64NMrSswhV50WdXzdb/Z5A==", "dev": true, "license": "MPL-2.0", "peer": true, @@ -8662,9 +8677,9 @@ "license": "MIT" }, "node_modules/baseline-browser-mapping": { - "version": "2.9.11", - "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.9.11.tgz", - "integrity": "sha512-Sg0xJUNDU1sJNGdfGWhVHX0kkZ+HWcvmVymJbj6NSgZZmW/8S9Y2HQ5euytnIgakgxN6papOAWiwDo1ctFDcoQ==", + "version": "2.9.13", + "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.9.13.tgz", + "integrity": "sha512-WhtvB2NG2wjr04+h77sg3klAIwrgOqnjS49GGudnUPGFFgg7G17y7Qecqp+2Dr5kUDxNRBca0SK7cG8JwzkWDQ==", "license": "Apache-2.0", "bin": { "baseline-browser-mapping": "dist/cli.js" @@ -8915,9 +8930,9 @@ } }, "node_modules/caniuse-lite": { - "version": "1.0.30001762", - "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001762.tgz", - "integrity": "sha512-PxZwGNvH7Ak8WX5iXzoK1KPZttBXNPuaOvI2ZYU7NrlM+d9Ov+TUvlLOBNGzVXAntMSMMlJPd+jY6ovrVjSmUw==", + "version": "1.0.30001763", + "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001763.tgz", + "integrity": "sha512-mh/dGtq56uN98LlNX9qdbKnzINhX0QzhiWBFEkFfsFO4QyCvL8YegrJAazCwXIeqkIob8BlZPGM3xdnY+sgmvQ==", "funding": [ { "type": "opencollective", @@ -9474,14 +9489,14 @@ "license": "MIT" }, "node_modules/cypress": { - "version": "15.8.1", - "resolved": "https://registry.npmjs.org/cypress/-/cypress-15.8.1.tgz", - "integrity": "sha512-ogc62stTQGh1395ipKxfCE5hQuSApTzeH5e0d9U6m7wYO9HQeCpgnkYtBtd0MbkN2Fnch5Od2mX9u4hoTlrH4Q==", + "version": "15.8.2", + "resolved": "https://registry.npmjs.org/cypress/-/cypress-15.8.2.tgz", + "integrity": "sha512-KGpuiE8o9l9eyVLPkig574t8zOXkEDKzI0a+RQwy4cfXzpaLipvTOv0t+QEEkLiw/8HbgMNZ0fbPKakJAB3USA==", "dev": true, "hasInstallScript": true, "license": "MIT", "dependencies": { - "@cypress/request": "^3.0.9", + "@cypress/request": "^3.0.10", "@cypress/xvfb": "^1.2.4", "@types/sinonjs__fake-timers": "8.1.1", "@types/sizzle": "^2.3.2", @@ -10333,9 +10348,9 @@ } }, "node_modules/eslint-plugin-cypress": { - "version": "5.2.0", - "resolved": "https://registry.npmjs.org/eslint-plugin-cypress/-/eslint-plugin-cypress-5.2.0.tgz", - "integrity": "sha512-vuCUBQloUSILxtJrUWV39vNIQPlbg0L7cTunEAzvaUzv9LFZZym+KFLH18n9j2cZuFPdlxOqTubCvg5se0DyGw==", + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/eslint-plugin-cypress/-/eslint-plugin-cypress-5.2.1.tgz", + "integrity": "sha512-HTJLbcd7fwJ4agbHinZ4FUIl38bUTJT3BmH8zdgS2V32LETmPqCtWHi3xlgZ2vpX0aW6kQoHCVVqHm8NxZJ9sA==", "dev": true, "license": "MIT", "dependencies": { @@ -17483,9 +17498,9 @@ } }, "node_modules/systeminformation": { - "version": "5.29.1", - "resolved": "https://registry.npmjs.org/systeminformation/-/systeminformation-5.29.1.tgz", - "integrity": "sha512-bBroZc2we1tpgTBKZL7JguBdObC1OY+eXAoEBdsTp3utfcCa8+jUf+Wq/intTCJmiKJcuLEPsjCU6uMye0qvsQ==", + "version": "5.30.2", + "resolved": "https://registry.npmjs.org/systeminformation/-/systeminformation-5.30.2.tgz", + "integrity": "sha512-Rrt5oFTWluUVuPlbtn3o9ja+nvjdF3Um4DG0KxqfYvpzcx7Q9plZBTjJiJy9mAouua4+OI7IUGBaG9Zyt9NgxA==", "dev": true, "license": "MIT", "os": [ diff --git a/package.json b/package.json index b1bc4b2..e3461aa 100644 --- a/package.json +++ b/package.json @@ -34,8 +34,8 @@ "dependencies": { "@emotion/react": "^11.14.0", "@emotion/styled": "^11.14.1", - "@mui/icons-material": "^7.3.6", - "@mui/material": "^7.3.6", + "@mui/icons-material": "^7.3.7", + "@mui/material": "^7.3.7", "@sentry/integrations": "^7.114.0", "@sentry/nextjs": "^10.32.1", "@vercel/speed-insights": "^1.3.1", @@ -53,19 +53,19 @@ "@svgr/webpack": "^8.1.0", "@testing-library/jest-dom": "^6.9.1", "@testing-library/react": "^16.3.1", - "@trivago/prettier-plugin-sort-imports": "^6.0.1", + "@trivago/prettier-plugin-sort-imports": "^6.0.2", "@types/jest": "^30.0.0", "@types/lodash": "^4.17.21", "@types/node": "^25.0.3", "@types/react": "^19.2.7", "@types/react-dom": "^19.2.3", - "caniuse-lite": "^1.0.30001762", + "caniuse-lite": "^1.0.30001763", "concurrently": "^9.2.1", - "cypress": "^15.8.1", + "cypress": "^15.8.2", "cypress-axe": "^1.7.0", "eslint": "^9.39.2", "eslint-config-prettier": "^10.1.8", - "eslint-plugin-cypress": "^5.2.0", + "eslint-plugin-cypress": "^5.2.1", "eslint-plugin-prettier": "^5.5.4", "eslint-plugin-react": "^7.37.5", "eslint-plugin-react-hooks": "^7.0.1", From 962724d258be8a0d312c6e1ca5f91c6ee9a9f353 Mon Sep 17 00:00:00 2001 From: Alexander Sullivan Date: Thu, 8 Jan 2026 10:49:11 -0500 Subject: [PATCH 4/8] index to readme --- .github/prompts/{index.md => readme.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .github/prompts/{index.md => readme.md} (100%) diff --git a/.github/prompts/index.md b/.github/prompts/readme.md similarity index 100% rename from .github/prompts/index.md rename to .github/prompts/readme.md From 21b504ebdf0962923f620772909945c9a2b94d17 Mon Sep 17 00:00:00 2001 From: Alexander Sullivan Date: Thu, 8 Jan 2026 15:56:24 +0000 Subject: [PATCH 5/8] maybe --- .github/prompts/audit-docs.prompt.md | 37 ++++++++++++++++++---------- 1 file changed, 24 insertions(+), 13 deletions(-) diff --git a/.github/prompts/audit-docs.prompt.md b/.github/prompts/audit-docs.prompt.md index 430408f..a75541a 100644 --- a/.github/prompts/audit-docs.prompt.md +++ b/.github/prompts/audit-docs.prompt.md @@ -12,7 +12,12 @@ labels: ## Role & Purpose -Act as a **Documentation Auditor**. Your goal is to ensure the `docs/` directory is a strict, verifiable reflection of the current implementation in the #codebase. +Act as a **Strictly Factual Technical Auditor**. Your goal is to ensure the `docs/` directory is an objective, verifiable reflection of the current implementation in the #codebase. + +**Core Philosophy:** + +- **Reporter, Not Editor:** You convert code facts into documentation. You do **not** decide what is "important," "critical," or "interesting" on your own. +- **Objective Reality:** If the code does X, document X. Do not add commentary on _how well_ it does X. **Audience Strategy (Dual Focus):** Documentation must serve two audiences simultaneously: @@ -22,8 +27,9 @@ Documentation must serve two audiences simultaneously: **Tone:** -- **Approachable:** Clear enough for a new person to pick up the systems quickly. -- **Technical:** Deep enough for experts to understand nuances and edge cases. +- **Approachable (For Concepts):** Use clear, simple natural language when introducing _what_ a system does. +- **Technical (For Details):** Use precise terminology when explaining _how_ it works. +- **Objective (For Adjectives):** See Hard Rule #2 below. --- @@ -67,16 +73,21 @@ Execute **Phase 1** and **Phase 2** in order. - Every single statement must be grounded in a specific line of the #codebase. - If you cannot point to the specific file and line number that proves a statement is true, do not write it. - No speculation on planned features. + - **Verification:** If the code implementation is ambiguous, do not guess. Skip it. -2. **No Placeholder Text or TODOs** +2. **Strict Objectivity (AI Generation vs. Human Preservation)** + - **Generation (New Content):** When _you_ write new documentation, do not use subjective adjectives like: _important, critical, robust, seamless, best-in-class._ Stick to verifiable facts. + - **Preservation (Existing Content):** If _existing_ human-written documentation or code comments already use these terms, **preserve them**. Do not sanitize human judgment. + - **The Line:** + - _Bad (AI Generated):_ "The `auth.ts` middleware is a critical component." (This is an opinion). + - _Good (AI Generated):_ "The `auth.ts` middleware blocks unauthorized requests." (This is a fact). + - _Good (Preserved):_ "Usage: 'Critical: Do not modify this flag.' (Source: `config.ts` comment)." + +3. **No Placeholder Text or TODOs** - Do not create empty sections or stubs. - Do not leave comments like "Add more details here." - Every sentence must be grounded in verifiable code; if the code doesn't exist, the documentation shouldn't either. -3. **Unify and Consolidate** - - If three files describe one feature, merge them into one authoritative file to reduce cognitive load. - - Write less content, but make it higher impact. - --- ## 3. Writing Guidelines: Citations, Brevity & Style @@ -102,12 +113,12 @@ Execute **Phase 1** and **Phase 2** in order. - **High-Density, Low-Volume:** - Avoid "Wall of Text." Use bullet points and headers to break up density. - - Do not narrate code line-by-line. Explain _why_ it exists and _how_ the system uses it. + - Do not narrate code line-by-line. Explain _why_ it exists (architecturally) and _how_ the system uses it. - **Zero Bloat:** If a sentence does not add strict technical value or learning clarity, do not add it. --- -## 4. Mermaid/Visual Diagrams (Strategic & Meaningful) +## 4. Mermaid Diagrams (Strategic & Meaningful) **Goal:** Proactively use **Mermaid** diagrams to visualize complexity. A picture is worth a thousand words. @@ -156,10 +167,10 @@ If you are documenting the following categories, a **Mermaid** diagram is **stro - _Did I hallucinate a function name or function logic?_ - _Is this path correct?_ - _Are my statements 100% verifiable and grounded in existing #codebase implementation?_ - - _Did I write unnecessary fluff? If yes, delete it._ - - **_Did I describe a complex flow (like a Data Flow or Architecture) but skip the Mermaid diagram? If yes, go back and add it._** + - _Did I insert NEW subjective words? (If yes, remove them. If preserving existing ones, keep them)._ + - **_Did I describe a complex flow (like Data Flow or Architecture) but skip the Mermaid diagram? If yes, go back and add it._** - _Did I cite the file for the logic I just explained? If not, find the file or delete the text._ -4. **Action:** If you find any discrepancy, missing citation/diagram, or bloat, correct it immediately before outputting. +4. **Action:** If you find any discrepancy, missing citation/diagram, subjectivity, or bloat, correct it immediately before outputting. --- From df72c9cc9f4e4ccb6b5fc5e922c5c0e8269d3d9f Mon Sep 17 00:00:00 2001 From: Alexander Sullivan Date: Thu, 8 Jan 2026 16:58:13 +0000 Subject: [PATCH 6/8] another update --- .github/prompts/audit-docs.prompt.md | 38 +++++++++++++++++----------- 1 file changed, 23 insertions(+), 15 deletions(-) diff --git a/.github/prompts/audit-docs.prompt.md b/.github/prompts/audit-docs.prompt.md index a75541a..720cc02 100644 --- a/.github/prompts/audit-docs.prompt.md +++ b/.github/prompts/audit-docs.prompt.md @@ -18,6 +18,7 @@ Act as a **Strictly Factual Technical Auditor**. Your goal is to ensure the `doc - **Reporter, Not Editor:** You convert code facts into documentation. You do **not** decide what is "important," "critical," or "interesting" on your own. - **Objective Reality:** If the code does X, document X. Do not add commentary on _how well_ it does X. +- **Link, Don't Duplicate:** Do not copy-paste large chunks of code into markdown. Point the reader to the source of truth. **Audience Strategy (Dual Focus):** Documentation must serve two audiences simultaneously: @@ -45,6 +46,7 @@ Execute **Phase 1** and **Phase 2** in order. 2. **Phase 2: General Audit (Mandatory)** - **Action:** Audit the entire `docs/` directory against the current #codebase. - **Task:** + - **Mandatory Correction:** If existing text describes behavior that contradicts the code (e.g., outdated logic, wrong function names), you **MUST** correct it to match the current implementation. - Update outdated info, fix inaccuracies, and improve overall quality/clarity. - Consolidate fragmented files to reduce noise. - **Create New Files & Directories (Strategic Expansion):** @@ -73,15 +75,16 @@ Execute **Phase 1** and **Phase 2** in order. - Every single statement must be grounded in a specific line of the #codebase. - If you cannot point to the specific file and line number that proves a statement is true, do not write it. - No speculation on planned features. - - **Verification:** If the code implementation is ambiguous, do not guess. Skip it. + - **No "Name-Based" Assumptions:** Do not assume a function does X just because it is named `doX`. Read the implementation logic. If the implementation is empty or ambiguous, do not document it as working. -2. **Strict Objectivity (AI Generation vs. Human Preservation)** +2. **Strict Objectivity (The Fact vs. Opinion Protocol)** + - **The Truth Override (CRITICAL):** If existing human-written documentation is factually incorrect (e.g., claims the system uses TCP when code shows UDP), you **MUST** correct it. Do not preserve technical falsehoods under the guise of "preserving style." - **Generation (New Content):** When _you_ write new documentation, do not use subjective adjectives like: _important, critical, robust, seamless, best-in-class._ Stick to verifiable facts. - - **Preservation (Existing Content):** If _existing_ human-written documentation or code comments already use these terms, **preserve them**. Do not sanitize human judgment. + - **Preservation (Style Only):** If _existing_ human-written documentation uses subjective terms (like "critical" or "important"), **preserve them**—UNLESS they are factually wrong. - **The Line:** - - _Bad (AI Generated):_ "The `auth.ts` middleware is a critical component." (This is an opinion). - - _Good (AI Generated):_ "The `auth.ts` middleware blocks unauthorized requests." (This is a fact). - - _Good (Preserved):_ "Usage: 'Critical: Do not modify this flag.' (Source: `config.ts` comment)." + - _Bad (AI Generated):_ "The `auth.ts` middleware is a critical component." (Opinion). + - _Good (AI Generated):_ "The `auth.ts` middleware blocks unauthorized requests." (Fact). + - _Correction Example:_ Existing doc says "Returns JSON." Code returns "XML." -> **Change to XML.** 3. **No Placeholder Text or TODOs** - Do not create empty sections or stubs. @@ -148,7 +151,10 @@ If you are documenting the following categories, a **Mermaid** diagram is **stro ## 5. Formatting Standards 1. **Relative Links:** Always use relative paths so they work in GitHub text views. -2. **Code Snippets:** Use sparingly. Only for non-obvious configurations or critical edge cases. +2. **Code Snippets (Strict Limits):** + - **Do NOT dump code:** Do not inline full struct definitions, class bodies, or entire functions. This is documentation, not a copy of the codebase. + - **Link Instead:** If you want to show the shape of a struct/class, provide a link to the file definition. + - **Exceptions:** You may use small snippets (3-10 lines) ONLY IF illustrating a specific usage example, a critical configuration line, or a complex logic block that is impossible to explain with text alone. 3. **Directory Structure:** If creating a new folder, it **must** have an `index.md` describing the directory's purpose. 4. **Related Documentation:** - **Scope:** Apply to standard `.md` files (Exclude `index.md` and `README.md`). @@ -163,14 +169,14 @@ If you are documenting the following categories, a **Mermaid** diagram is **stro 1. **Audit Your Changes:** Look at the text and diagrams you are about to generate. 2. **Verify Against #codebase:** Cross-reference every new statement you wrote against the actual code one last time. -3. **Check for Accuracy, Bloat, & Visuals:** - - _Did I hallucinate a function name or function logic?_ - - _Is this path correct?_ +3. **Check for Accuracy, Hallucinations & Bloat:** + - _Did I assume what a function does based on its name, or did I read the logic? (If assumed -> Verify it)._ - _Are my statements 100% verifiable and grounded in existing #codebase implementation?_ + - _**Did I verify if existing text matches the code? If it is outdated/wrong, did I correct it?**_ + - _Did I inline a full struct or class definition? (If yes -> Delete it and replace with a link)._ - _Did I insert NEW subjective words? (If yes, remove them. If preserving existing ones, keep them)._ - - **_Did I describe a complex flow (like Data Flow or Architecture) but skip the Mermaid diagram? If yes, go back and add it._** - _Did I cite the file for the logic I just explained? If not, find the file or delete the text._ -4. **Action:** If you find any discrepancy, missing citation/diagram, subjectivity, or bloat, correct it immediately before outputting. +4. **Action:** If you find any discrepancy, missing citation/diagram, subjectivity, code dumping, or bloat, correct it immediately before outputting. --- @@ -182,6 +188,8 @@ Before concluding this task, verify: 2. _Did I remove all placeholders?_ 3. _Did I properly define all acronyms on first use?_ 4. _Did I include meaningful Mermaid diagrams for complex systems?_ -5. _Did I place implementation citations at the end of sections?_ -6. _Did I run Phase 2 (General Audit) even if I made changes in Phase 1?_ -7. _Did I follow the Diátaxis Framework for any NEW directory structures?_ +5. _Did I replace massive code dumps with links?_ +6. _Did I place implementation citations at the end of sections?_ +7. _Did I correct factual errors in existing documentation?_ +8. _Did I run Phase 2 (General Audit) even if I made changes in Phase 1?_ +9. _Did I follow the Diátaxis Framework for any NEW directory structures?_ From 0087e0b1fc4f40ce73c24e445012f48392a11984 Mon Sep 17 00:00:00 2001 From: Alexander Sullivan Date: Thu, 8 Jan 2026 12:26:53 -0500 Subject: [PATCH 7/8] update docs --- docs/architecture/components/avatar.md | 30 ++++++++++--------------- docs/architecture/configs.md | 31 +++++++------------------- docs/architecture/images.md | 20 ++++++++--------- docs/architecture/layouts.md | 4 +++- docs/architecture/pwa.md | 5 ++++- docs/architecture/service-worker.md | 10 +++++++-- docs/usage/testing.md | 7 +++++- 7 files changed, 50 insertions(+), 57 deletions(-) diff --git a/docs/architecture/components/avatar.md b/docs/architecture/components/avatar.md index 7382d11..b1aea2c 100644 --- a/docs/architecture/components/avatar.md +++ b/docs/architecture/components/avatar.md @@ -179,19 +179,16 @@ useEffect(() => { ### Accessibility -The avatar container includes proper accessibility attributes: +The Avatar component uses the Next.js `Image` component with these accessibility attributes: - `data-testid='profile_pic'` - Testing identifier -- `aria-label='Profile picture'` - Screen reader label -- `role='img'` - Semantic role for assistive technologies -- `onMouseEnter={debounceHover}` - Hover interaction handler -- `sx` prop with `cursor: 'pointer'` to indicate interactivity - -The nested `Image` component includes: - -- `alt='Alexander Sullivan profile picture'` - Descriptive alt text -- `width={200}` and `height={200}` - Explicit dimensions -- `priority` - Next.js optimization for above-the-fold content +- `aria-label='Profile Picture for Alexander Sullivan'` - Screen reader label +- `alt='Alexander Sullivan head drawn and stylized'` - Descriptive alt text +- `width={500}` and `height={500}` - Explicit dimensions for Next.js optimization +- `priority` - Optimizes loading for above-the-fold content +- `onClick={debounceSneeze}` - Click interaction handler (in addition to mouse enter) +- `onMouseEnter={debounceSneeze}` - Hover interaction handler +- `style` prop with `cursor: 'pointer'` via borderRadius and positioning ## Component Interaction @@ -229,10 +226,7 @@ Test file: [`src/components/banner/Avatar.test.tsx`](../../src/components/banner ## Related Documentation -- [Helpers: AAAAHHHH](./helpers.md#aaaahhhh-helper) -- [Components Overview](./components/index.md) -- [Firebase Analytics](./configs.md#firebase-configuration-and-usage) - ---- - -💡 **Tip:** Try hovering over the profile picture to discover the sneeze animation and Easter egg! +- [Helpers: AAAAHHHH](../helpers.md#aaaahhhh-easter-egg-helper) +- [Components Overview](./index.md) +- [Firebase Analytics](../configs.md) +- [Constants](../constants.md) diff --git a/docs/architecture/configs.md b/docs/architecture/configs.md index a086add..027cb7b 100644 --- a/docs/architecture/configs.md +++ b/docs/architecture/configs.md @@ -2,11 +2,13 @@ This document describes configuration files and environment setup in AlexJSully's Portfolio project, their roles, technical details, and how to update or extend them. -## 📦 Purpose +Implementation: [firebase.ts](../../src/configs/firebase.ts), [next.config.js](../../next.config.js) + +## Purpose Configs manage environment variables, service integrations, and global settings for the app. They enable features like Firebase, Sentry error tracking, and custom runtime options. -## 🏗️ Structure +## Structure - **Location:** `src/configs/` - **Example files:** @@ -17,7 +19,7 @@ Configs manage environment variables, service integrations, and global settings - `next.config.js`: Next.js build/runtime config - `sentry.client.config.ts`, `sentry.server.config.ts`, `sentry.edge.config.ts`: Sentry error tracking -## 🔍 Usage Examples +## Usage Examples ### Firebase configuration and usage @@ -63,36 +65,19 @@ module.exports = { }; ``` -## 🧩 Integration & Relationships +## Integration & Relationships - Configs are imported by components, helpers, and backend logic for environment-specific behavior. - Environment variables are loaded via `.env` and referenced in code using `process.env.*`. - Sentry config files enable error tracking for client, server, and edge runtimes. -## 🛠️ Extending Configs +## Extending Configs - Add new config files in `src/configs/` for new services. - Update `.env` for new environment variables. - Document config changes in `README.md` and relevant docs. -## 🔗 Related Docs +## Related Docs - [System Architecture](./index.md) - - [PWA Documentation](./pwa.md) - -💡 **Tip:** Keep sensitive keys in `.env` and never commit them to version control. Document all config changes for maintainability. - -## 🛠️ Practical Guidance - -- Store sensitive keys and secrets in `.env` (never commit to git). -- Document required environment variables for contributors in README.md or a dedicated section. -- Update config files when adding new services or changing integrations. -- Validate config changes with `npm run validate`. -- For Sentry, update DSN and environment in all sentry config files and test error reporting. - -## 🧩 Relationships - -- Used by data modules, components, and Next.js for service integration. -- Sentry configs for error tracking. -- Firebase config for backend/data features. diff --git a/docs/architecture/images.md b/docs/architecture/images.md index b70d56b..e7156e4 100644 --- a/docs/architecture/images.md +++ b/docs/architecture/images.md @@ -1,12 +1,14 @@ # Images & Icons Documentation -This document explains how images and icons are used, organized, and named in AlexJSully's Portfolio project, and how contributors can add their own. +This document explains how images and icons are used, organized, and named in Alexander Sullivan's Portfolio project, and how contributors can add their own. -## 📦 Purpose +Implementation: [icons.tsx](../../src/images/icons.tsx), [public/images/](../../public/images/) + +## Purpose Images and icons provide visual context, branding, and UI elements throughout the portfolio. They are used for project thumbnails, profile pictures, social media links, and custom graphics. -## 🏗️ Structure +## Structure ### Images @@ -25,7 +27,7 @@ Images and icons provide visual context, branding, and UI elements throughout th - **Usage:** - Social media links, UI buttons, branding, and navigation -## 📝 Naming Conventions +## Naming Conventions ### Image Naming @@ -38,7 +40,7 @@ Images and icons provide visual context, branding, and UI elements throughout th - Social: `github.svg`, `linkedin.svg`, `twitter.svg`, etc. - UI: Use clear, lowercase names (e.g., `bar.svg`, `publish.svg`) -## 🔍 Usage Examples +## Usage Examples ### Using Images in Components @@ -83,17 +85,13 @@ import GitHubIcon from '@images/icons/github.svg'; 3. Import it in your component as shown above. 4. Use with MUI `IconButton` or directly in JSX. -## 🧩 Relationships +## Relationships - Images are referenced in data files (e.g., `projects.ts`) and components. - Icons are imported as React components or used in MUI IconButton. - Both are essential for UI consistency and branding. -## 🔗 Related Docs +## Related Documentation - [Component Documentation](./components/index.md) - [Projects Guide](./components/projects.md) - ---- - -💡 **Tip:** Use `.webp` for images when possible for better performance. Keep icon names lowercase and descriptive. Always optimize images for web. diff --git a/docs/architecture/layouts.md b/docs/architecture/layouts.md index 9a912c6..0213921 100644 --- a/docs/architecture/layouts.md +++ b/docs/architecture/layouts.md @@ -2,6 +2,8 @@ This document describes the layout system in the Alexander Sullivan's Portfolio project. +Implementation: [GeneralLayout.tsx](../../src/layouts/GeneralLayout.tsx) + ## Purpose Layouts define the structure and composition of pages and sections, ensuring consistent UI, navigation, and shared component behavior across the entire site. @@ -63,7 +65,7 @@ To create a new layout variant: 4. Use in appropriate page files 5. Add corresponding `.test.tsx` file -## Related Docs +## Related Documentation - [System Architecture](./index.md) - [App Directory & Routing](./app-directory.md) diff --git a/docs/architecture/pwa.md b/docs/architecture/pwa.md index a46decf..44ee0f2 100644 --- a/docs/architecture/pwa.md +++ b/docs/architecture/pwa.md @@ -2,6 +2,8 @@ This document explains how Progressive Web App (PWA) features are implemented in the Alexander Sullivan's Portfolio project using native Next.js capabilities. +Implementation: [manifest.ts](../../src/app/manifest.ts) + ## Purpose PWA support enables: @@ -77,7 +79,8 @@ To modify PWA settings: 2. **Icons**: Add or replace images in `public/icon/` and update the manifest accordingly. 3. **Service Worker**: Edit `public/sw.js` to customize caching strategies or precached assets. -## Related Docs +## Related Documentation - [Architecture Overview](./index.md) +- [Service Worker Implementation](./service-worker.md) - [Next.js Manifest Documentation](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/manifest) diff --git a/docs/architecture/service-worker.md b/docs/architecture/service-worker.md index 92610b4..84ceb61 100644 --- a/docs/architecture/service-worker.md +++ b/docs/architecture/service-worker.md @@ -17,7 +17,9 @@ This file documents the service worker implementation used by the site. ## How the app registers the service worker -The app registers the SW from a client component that runs inside the browser: +The app registers the SW from two locations: + +**ServiceWorkerRegister component** ([src/components/ServiceWorkerRegister.tsx](../../src/components/ServiceWorkerRegister.tsx)): ```tsx import { useEffect } from 'react'; @@ -36,7 +38,11 @@ export default function ServiceWorkerRegister() { } ``` -The home page (`src/app/page.tsx`) also attempts to register the same `'/sw.js'` as a defensive measure for client navigations. +**Home page** ([src/app/page.tsx](../../src/app/page.tsx)) also registers the SW within its `useEffect` as a defensive measure for client-side navigations. + +Both registration points use identical registration logic to ensure the service worker is registered regardless of entry point. + +Implementation: [ServiceWorkerRegister.tsx](../../src/components/ServiceWorkerRegister.tsx), [page.tsx](../../src/app/page.tsx) ## Customizing caching diff --git a/docs/usage/testing.md b/docs/usage/testing.md index b6d7d51..1bfb8e9 100644 --- a/docs/usage/testing.md +++ b/docs/usage/testing.md @@ -4,6 +4,8 @@ This document explains how the testing setup works in this codebase and how to run each test. If you want to contribute to this repository, please refer to the [Contributing Guide](../../CONTRIBUTING.md). +Implementation: [cypress.config.ts](../../cypress.config.ts), [jest.config.js](../../jest.config.js) + ## Testing Setup The testing setup in this codebase uses Cypress for end-to-end (E2E) testing. The configuration for Cypress is located in [cypress.config.ts](../../cypress.config.ts). @@ -127,4 +129,7 @@ This repository uses a CI workflow defined in [code-qa.yml](../../.github/workfl If you want to contribute to this repository, please refer to the [Contributing Guide](../../CONTRIBUTING.md) for more details on the pull request process and code of conduct. -By following these steps, you can successfully run and contribute to the tests in this codebase. +## Related Documentation + +- [Contributing Guide](../../CONTRIBUTING.md) +- [Setup & Installation](./setup.md) From a4c5494a99d0445116eaf183353791cbd007441d Mon Sep 17 00:00:00 2001 From: Alexander Sullivan Date: Thu, 8 Jan 2026 12:29:54 -0500 Subject: [PATCH 8/8] Update .github/prompts/audit-docs.prompt.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/prompts/audit-docs.prompt.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/prompts/audit-docs.prompt.md b/.github/prompts/audit-docs.prompt.md index 720cc02..2949f96 100644 --- a/.github/prompts/audit-docs.prompt.md +++ b/.github/prompts/audit-docs.prompt.md @@ -52,10 +52,10 @@ Execute **Phase 1** and **Phase 2** in order. - **Create New Files & Directories (Strategic Expansion):** - **Step 1: Check Existing Structure.** Before creating anything, scan `docs/`. If a logical home exists, place the file there. - **Step 2: Apply Diátaxis Framework.** If a **NEW** directory is required, or the content is a distinct new system, organize it using the **Diátaxis** structure: - - _Tutorials_ (Learning-oriented) - - _How-To Guides_ (Problem-oriented) - - _Reference_ (Information-oriented) - - _Explanation_ (Understanding-oriented) + - _Tutorials_ (Learning-oriented): step-by-step introductions that take a newcomer from zero to a working outcome. Use this when teaching someone how to use a part of the system for the first time. + - _How-To Guides_ (Problem-oriented): focused recipes that solve a specific, real-world task. Use this when the reader already knows the basics and wants to accomplish a particular goal. + - _Reference_ (Information-oriented): factual, exhaustive descriptions of APIs, components, configuration options, and behaviors. Use this when documenting “what exists” and its exact inputs/outputs. + - _Explanation_ (Understanding-oriented): background, rationale, and architectural overviews. Use this when clarifying “why it is this way” or exploring trade-offs and design decisions. - **Scope:** Create new artifacts for: - **New Components:** Systems, designs, modules or architecture that do not fit into existing files. - **External APIs:** Dedicated usage guides for external consumers.