From 16d4f816152322923bec3e8343b631d88fa15239 Mon Sep 17 00:00:00 2001 From: Navid Shad Date: Sat, 31 Jan 2026 18:49:48 +0200 Subject: [PATCH 1/5] feat: Enhance `development/SKILL.md` with E2E testing and navigation guidelines, and new principles for testing, documentation, and UI component usage. --- .agent/development/SKILL.md | 41 ++++++++++++++++++++++++++++++++++--- .agent/e2e/SKILL.md | 35 ------------------------------- 2 files changed, 38 insertions(+), 38 deletions(-) delete mode 100644 .agent/e2e/SKILL.md diff --git a/.agent/development/SKILL.md b/.agent/development/SKILL.md index 7e172b2..335c046 100644 --- a/.agent/development/SKILL.md +++ b/.agent/development/SKILL.md @@ -7,7 +7,16 @@ description: Core development guidelines and documentation for the Subturtle/Cod ## General Principles -- **Modularity**: Prioritize modularity in all code changes. Organize logic into distinct modules (Server-side) or reusable components (Frontend). +- **Modularity**: Prioritize modularity and separation of concerns. Organize logic into distinct, independent modules (Server-side) or reusable components (Frontend). Each module should have a single responsibility and a clear interface. +- **Testing**: + - Write unit tests for core logic and services. + - Implement integration tests for API endpoints and complex component interactions. + - Ensure tests are easy to run and provide clear feedback. +- **Human-friendly Documentation**: + - Write code that is self-documenting through clear naming conventions. + - Use JSDoc for functions and classes to document parameters, return values, and behavior. + - Add context-rich inline comments for complex logic, explaining the "why" rather than just the "what". + - Maintain up-to-date documentation within the `.agent/development` directory. - **ClickUp Integration**: - Task management primarily relies on ClickUp. - Always reference the ClickUp task ID in commit messages. Format: `feat: #taskid message`. @@ -34,8 +43,34 @@ Always refer to the official documentation for package-specific implementations: ### UI Components (lib-vue-components) - **Primary Docs**: [lib-vue-components.md](./lib-vue-components.md) - **Key Patterns**: - - Import components directly from `@codebridger/lib-vue-components` as needed (e.g., `import { Button } from '@codebridger/lib-vue-components'`). - - Follow the design system guidelines for consistent aesthetics. + - **Extensive Usage**: Prioritize and extensively use components from `@codebridger/lib-vue-components`. + - **Custom Components**: Only create custom components if no equivalent exists within the library. + - **Direct Imports**: Import components directly from `@codebridger/lib-vue-components` as needed (e.g., `import { Button } from '@codebridger/lib-vue-components'`). + - **Design Consistency**: Strictly follow the design system guidelines for consistent aesthetics. + +## E2E Testing and Navigation + +### Prerequisites +1. **Server**: Ensure the server is running (usually on port 8080). +2. **Frontend**: Ensure the frontend is running (usually on port 3000). + +### Authentication Flow +The application uses hash-based routing. To authenticate via token: +1. **Initial Navigation**: Open the website with the expected path (e.g., `http://localhost:3000/#/settings`). +2. **Manual Login (if needed)**: If you face the login page, use browser tools to store the token in the browser's local storage with the key `token` (e.g., `localStorage.setItem('token', 'YOUR_TOKEN')`). +3. **Re-navigate**: Enter the expected path again or reload the page to access the authenticated route. + +### Navigation Structure +- Home/Overview: `/#/` +- Board (Learning System): `/#/board` +- Statistic: `/#/statistic` +- Sessions: `/#/sessions` +- Settings: `/#/settings` + +### Troubleshooting +- **Blank Page**: Check browser console for authentication errors. +- **Login Redirect**: If redirected to `/#/auth/login`, the token might be invalid, expired, or not correctly set in local storage. +- **Missing Hash**: Always ensure the URL contains `/#/` after the origin due to `hashMode: true`. --- diff --git a/.agent/e2e/SKILL.md b/.agent/e2e/SKILL.md deleted file mode 100644 index b636dd5..0000000 --- a/.agent/e2e/SKILL.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -name: e2e -description: End-to-end navigation and testing guide for Subturtle Dashboard ---- - -This skill provides specific instructions for navigating and testing the Subturtle Dashboard application using browser tools. - -## Prerequisites -1. **Server**: Ensure the server is running (usually on port 8080). -2. **Frontend**: Ensure the frontend is running (usually on port 3000). - -## Authentication Flow -The application uses hash-based routing (`hashMode: true` in Nuxt config). To authenticate via token, you MUST include the `#` character in the URL. - -**Correct URL Template:** -`http://localhost:3000/#/auth/login_with_token?token={YOUR_TOKEN}` - -### Steps for Browser Agents: -1. **Navigate**: Use the `open_browser_url` tool with the correct hash-based login URL. -2. **Wait for Redirect**: The `login_with_token` page is a redirection page. Wait at least 3 seconds for the `onMounted` hook to process the token and redirect to the dashboard. -3. **Verify Dashboard**: After redirection, verify you are on `/#/` or another authenticated route. Use `capture_browser_screenshot` to confirm the UI has loaded. -4. **Inspect UI**: Once logged in, use the navigation menu or direct hash-links to find the specific page. - -## Navigation Structure -- Home/Overview: `/#/` -- Board (Learning System): `/#/board` -- Statistic: `/#/statistic` -- Sessions: `/#/sessions` -- Settings: `/#/settings` - -## Troubleshooting -- **Blank Page**: Check browser console for authentication errors. -- **Login Redirect**: If redirected to `/#/auth/login`, the token might be invalid or expired. -- **Missing Hash**: Always ensure the URL contains `/#/` after the origin. -- **Login Issue**: If you are not logged in, try to store the token in the browser's local storage `token={YOUR_TOKEN}` and then navigate to the dashboard. \ No newline at end of file From 09972611634b826c33bd8c37a2fe4d486188ea48 Mon Sep 17 00:00:00 2001 From: Navid Shad Date: Sat, 31 Jan 2026 19:07:41 +0200 Subject: [PATCH 2/5] refactor: reorganize agent development files into categorized skill directories. --- .agent/development/SKILL.md | 78 ---------- .agent/skills/backend/SKILL.md | 28 ++++ .../backend}/modular-rest_server.md | 0 .agent/skills/frontend/SKILL.md | 32 +++++ .../frontend}/modular-rest_client.md | 0 .agent/skills/frontend_design/SKILL.md | 135 ++++++++++++++++++ .../frontend_design}/lib-vue-components.md | 0 7 files changed, 195 insertions(+), 78 deletions(-) delete mode 100644 .agent/development/SKILL.md create mode 100644 .agent/skills/backend/SKILL.md rename .agent/{development => skills/backend}/modular-rest_server.md (100%) create mode 100644 .agent/skills/frontend/SKILL.md rename .agent/{development => skills/frontend}/modular-rest_client.md (100%) create mode 100644 .agent/skills/frontend_design/SKILL.md rename .agent/{development => skills/frontend_design}/lib-vue-components.md (100%) diff --git a/.agent/development/SKILL.md b/.agent/development/SKILL.md deleted file mode 100644 index 335c046..0000000 --- a/.agent/development/SKILL.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -name: CodeBridger Development Skill -description: Core development guidelines and documentation for the Subturtle/CodeBridger ecosystem. Triggered when working on dashboard-app or server. ---- - -# Development Guidelines - -## General Principles - -- **Modularity**: Prioritize modularity and separation of concerns. Organize logic into distinct, independent modules (Server-side) or reusable components (Frontend). Each module should have a single responsibility and a clear interface. -- **Testing**: - - Write unit tests for core logic and services. - - Implement integration tests for API endpoints and complex component interactions. - - Ensure tests are easy to run and provide clear feedback. -- **Human-friendly Documentation**: - - Write code that is self-documenting through clear naming conventions. - - Use JSDoc for functions and classes to document parameters, return values, and behavior. - - Add context-rich inline comments for complex logic, explaining the "why" rather than just the "what". - - Maintain up-to-date documentation within the `.agent/development` directory. -- **ClickUp Integration**: - - Task management primarily relies on ClickUp. - - Always reference the ClickUp task ID in commit messages. Format: `feat: #taskid message`. -- **Communication**: - - Favor answering questions and providing explanations over direct code modifications unless explicitly requested. - - Ensure all explanations are clear and provide necessary context. - -## Framework Documentation - -Always refer to the official documentation for package-specific implementations: - -### Server-Side (@modular-rest/server) -- **Primary Docs**: [modular-rest_server.md](./modular-rest_server.md) -- **Key Patterns**: - - Use `defineCollection` in `db.ts` for database models. - - Use `defineFunction` in `functions.ts` for API logic. - - Avoid manual router creation unless necessary (`router.ts`). - -### Frontend-Side (@modular-rest/client) -- **Primary Docs**: [modular-rest_client.md](./modular-rest_client.md) -- **Key Patterns**: - - Reference the JS client for consuming services and calling server functions. - -### UI Components (lib-vue-components) -- **Primary Docs**: [lib-vue-components.md](./lib-vue-components.md) -- **Key Patterns**: - - **Extensive Usage**: Prioritize and extensively use components from `@codebridger/lib-vue-components`. - - **Custom Components**: Only create custom components if no equivalent exists within the library. - - **Direct Imports**: Import components directly from `@codebridger/lib-vue-components` as needed (e.g., `import { Button } from '@codebridger/lib-vue-components'`). - - **Design Consistency**: Strictly follow the design system guidelines for consistent aesthetics. - -## E2E Testing and Navigation - -### Prerequisites -1. **Server**: Ensure the server is running (usually on port 8080). -2. **Frontend**: Ensure the frontend is running (usually on port 3000). - -### Authentication Flow -The application uses hash-based routing. To authenticate via token: -1. **Initial Navigation**: Open the website with the expected path (e.g., `http://localhost:3000/#/settings`). -2. **Manual Login (if needed)**: If you face the login page, use browser tools to store the token in the browser's local storage with the key `token` (e.g., `localStorage.setItem('token', 'YOUR_TOKEN')`). -3. **Re-navigate**: Enter the expected path again or reload the page to access the authenticated route. - -### Navigation Structure -- Home/Overview: `/#/` -- Board (Learning System): `/#/board` -- Statistic: `/#/statistic` -- Sessions: `/#/sessions` -- Settings: `/#/settings` - -### Troubleshooting -- **Blank Page**: Check browser console for authentication errors. -- **Login Redirect**: If redirected to `/#/auth/login`, the token might be invalid, expired, or not correctly set in local storage. -- **Missing Hash**: Always ensure the URL contains `/#/` after the origin due to `hashMode: true`. - - ---- - -You must read the specific documentation files listed above before proposing or implementing any technical changes related to these packages. \ No newline at end of file diff --git a/.agent/skills/backend/SKILL.md b/.agent/skills/backend/SKILL.md new file mode 100644 index 0000000..193f733 --- /dev/null +++ b/.agent/skills/backend/SKILL.md @@ -0,0 +1,28 @@ +--- +name: Backend Development +description: Guidelines for Server-side development using Modular Rest, Database schemas, and Business Logic. +--- + +# Backend Development Skill + +## 1. Core Principles +- **Modularity**: Organize logic into distinct, independent modules. Each module should have a single responsibility. +- **Testing**: Write unit tests for core logic and services. +- **Documentation**: Use JSDoc for functions to document parameters and return values. +- **Workflow**: Always reference the ClickUp task ID in commit messages (e.g., `feat: #taskid message`). + +## 2. Technology Stack +- **Framework**: Modular Rest Server (@modular-rest/server) +- **Database**: MongoDB (via `defineCollection`) + +## 3. Documentation Reference +**You MUST read the following file for API details:** +- [Modular Rest Server Docs](./modular-rest_server.md) + +## 4. Key Patterns +- **Database Models**: Use `defineCollection` in `db.ts` files within modules. +- **API Functions**: Use `defineFunction` in `functions.ts` files. +- **Routing**: Avoid manual router creation; let the framework handle it. + +## 5. Directory Structure +Code should be written in `/Users/navid-shad/Projects/CodeBridger/learn-by-subtitle/dashboard-app/server`. diff --git a/.agent/development/modular-rest_server.md b/.agent/skills/backend/modular-rest_server.md similarity index 100% rename from .agent/development/modular-rest_server.md rename to .agent/skills/backend/modular-rest_server.md diff --git a/.agent/skills/frontend/SKILL.md b/.agent/skills/frontend/SKILL.md new file mode 100644 index 0000000..3824523 --- /dev/null +++ b/.agent/skills/frontend/SKILL.md @@ -0,0 +1,32 @@ +--- +name: Frontend Logic +description: Guidelines for Client-side logic, State Management (Pinia), API Integration, and App Navigation. +--- + +# Frontend Logic Skill + +## 1. Core Principles +- **State Management**: Use Pinia for global state. +- **API Integration**: Use `@modular-rest/client` to call server functions. +- **Testing**: Implement integration tests for complex component interactions. +- **Workflow**: Always reference the ClickUp task ID in commit messages (e.g., `feat: #taskid message`). + +## 2. Documentation Reference +**You MUST read the following file for API Client details:** +- [Modular Rest Client Docs](./modular-rest_client.md) + +## 3. Navigation & Auth Flow +The application uses hash-based routing (`/#/`). + +### Common Routes +- Home: `/#/` +- Board: `/#/board` +- Settings: `/#/settings` + +### Authentication +- Token is stored in `localStorage` key `token`. +- If redirected to login, verify token presence. + +## 4. Key Patterns +- **Services**: Import `functionProvider` from `@modular-rest/client` to execute backend functions. +- **Composables**: Use Vue composables for reusable logic. diff --git a/.agent/development/modular-rest_client.md b/.agent/skills/frontend/modular-rest_client.md similarity index 100% rename from .agent/development/modular-rest_client.md rename to .agent/skills/frontend/modular-rest_client.md diff --git a/.agent/skills/frontend_design/SKILL.md b/.agent/skills/frontend_design/SKILL.md new file mode 100644 index 0000000..94f8b6f --- /dev/null +++ b/.agent/skills/frontend_design/SKILL.md @@ -0,0 +1,135 @@ +--- +name: Frontend Design System +description: Comprehensive guide for creating premium, high-fidelity UI layouts using the project's Vue component library and Tailwind CSS. +--- + +# Frontend Design System + +This skill provides the standards and patterns for building user interfaces in the dashboard application. The goal is to create a **premium, dynamic, and highly polished** user experience that "wows" the user. + +## 1. Design Philosophy + +- **High-End Aesthetics**: We do not build "MVP-looking" apps. We build refined, polished interfaces. +- **Glassmorphism & Depth**: Utilize layers, blurs (`backdrop-blur-xl`), and subtle transparencies (`bg-white/40`) to create depth. +- **Vibrant Colors**: Use the project's `primary` and `secondary` palette, but often via gradients or low-opacity tints (`bg-primary/10`) rather than solid blocks of harsh color. +- **Dynamic Motion**: Nothing should feel static. Smooth transitions (`duration-500`, `duration-700`), micro-interactions on hover, and entrance animations are required. + +## 2. Component Usage + +All standard UI elements must come from the internal component library. + +**Reference Documentation:** +- [UI Component Library (lib-vue-components)](./lib-vue-components.md) - Contains full list of available components and their props. + +```typescript +// Import path +import { Card, Button, Icon } from '@codebridger/lib-vue-components/elements.ts'; +import { Modal } from '@codebridger/lib-vue-components/complex.ts'; +``` + +### Key Components +- **Card**: The building block for content. +- **Button**: Use for actions. +- **Icon**: Wrapper for Iconify icons. PREFERRED SET: `iconify solar--*-bold-duotone` or `*-bold`. + +## 3. Layout Patterns + +### Main Page Shell +Pages normally live within a `DashboardShell` (via `default` layout). Content should be centered with max-width. + +```vue + +``` + +### Card Styling +Cards should rarely be just plain rectangles. + +**Premium Card Recipe:** +- **Rounding**: `rounded-[2.5rem]` or `rounded-3xl` (generous curves). +- **Background**: `bg-white dark:bg-gray-800`. +- **Shadow**: Light idle shadow `shadow-[0_4px_20px_rgba(0,0,0,0.03)]` -> Deep hover shadow `hover:shadow-[0_40px_80px_rgba(var(--primary-rgb),0.15)]`. +- **Interaction**: `group hover:-translate-y-3 transition-all duration-700`. +- **Decorations**: Use absolute positioned gradients or icons in the background of cards to add texture. + +## 4. Typography Standards + +- **Titles (H1-H2)**: `font-black`, `tracking-tight`. +- **Body**: `font-medium` (avoid thin weights for body text to maintain legibility and premium feel). +- **Labels/Meta**: `text-[10px]` or `text-xs`, `font-bold`, `uppercase`, `tracking-widest` (typographic spacing is key for the premium look). +- **Colors**: + - Primary text: `text-gray-900` / `dark:text-white` + - Secondary text: `text-gray-500` / `dark:text-gray-400` + - Accent text: `text-primary` + +## 5. Visual Effects & Assets + +### Gradients +Use gradients to create "glows". +- *Example*: `bg-gradient-to-br from-primary via-primary-dark to-secondary` + +### Glassmorphism +- Use `backdrop-blur-md` or `backdrop-blur-xl`. +- Combine with `bg-white/10` or `bg-white/70`. +- Add `border border-white/20` for the "glass edge" look. + +### Background Elements +Add "blobs" behind the main content to avoid empty whitespace looking boring. +```html +
+``` + +## 6. Development Checklist + +When creating a new page or component: +1. [ ] Did I use `Card` and `Button` from the library? +2. [ ] Are the borders rounded enough (`rounded-2xl+`)? +3. [ ] Is there an entrance animation (e.g., `animate-fade-in-up`)? +4. [ ] Are interactable elements responsive to hover (scale, shadow, lift)? +5. [ ] Is Dark Mode supported (`dark:` variants)? +6. [ ] Did I use the "Solar" icon set (`iconify solar--...`)? +7. [ ] Is the typography hierarchy clear (Big titles, tiny uppercase labels)? diff --git a/.agent/development/lib-vue-components.md b/.agent/skills/frontend_design/lib-vue-components.md similarity index 100% rename from .agent/development/lib-vue-components.md rename to .agent/skills/frontend_design/lib-vue-components.md From d5aff848fafdd790fdf06c4bf3809fdaf71009b9 Mon Sep 17 00:00:00 2001 From: Navid Shad Date: Sun, 1 Feb 2026 15:33:52 +0200 Subject: [PATCH 3/5] refactor: #86ewevg3y Redesign bundle list and detail pages with a new layout, decorative background elements, and improved empty states. --- frontend/pages/bundles/[id].vue | 305 +++++++++++++++++-------------- frontend/pages/bundles/index.vue | 139 +++++++++----- 2 files changed, 258 insertions(+), 186 deletions(-) diff --git a/frontend/pages/bundles/[id].vue b/frontend/pages/bundles/[id].vue index a232351..ecadf2f 100644 --- a/frontend/pages/bundles/[id].vue +++ b/frontend/pages/bundles/[id].vue @@ -1,161 +1,186 @@ diff --git a/frontend/pages/bundles/index.vue b/frontend/pages/bundles/index.vue index 08061c8..4a1779e 100644 --- a/frontend/pages/bundles/index.vue +++ b/frontend/pages/bundles/index.vue @@ -1,57 +1,104 @@ From 93731d9aeb9023245b8c5053cb22e7ad75d48b64 Mon Sep 17 00:00:00 2001 From: Navid Shad Date: Sun, 1 Feb 2026 15:43:43 +0200 Subject: [PATCH 4/5] feat: #86ewevg3y Implement common `PageHeader` and `Breadcrumb` components, updating bundle pages and documentation. --- .agent/skills/frontend_design/SKILL.md | 35 ++-- frontend/components/common/Breadcrumb.vue | 39 +++++ frontend/components/common/PageHeader.vue | 51 ++++++ frontend/pages/bundles/[id].vue | 9 +- frontend/pages/bundles/index.vue | 198 +++++++++------------- 5 files changed, 187 insertions(+), 145 deletions(-) create mode 100644 frontend/components/common/Breadcrumb.vue create mode 100644 frontend/components/common/PageHeader.vue diff --git a/.agent/skills/frontend_design/SKILL.md b/.agent/skills/frontend_design/SKILL.md index 94f8b6f..dc0317a 100644 --- a/.agent/skills/frontend_design/SKILL.md +++ b/.agent/skills/frontend_design/SKILL.md @@ -31,6 +31,8 @@ import { Modal } from '@codebridger/lib-vue-components/complex.ts'; - **Card**: The building block for content. - **Button**: Use for actions. - **Icon**: Wrapper for Iconify icons. PREFERRED SET: `iconify solar--*-bold-duotone` or `*-bold`. +- **PageHeader**: Standard top-of-page layout with title, subtitle, and actions. +- **Breadcrumb**: Navigation hierarchy component. ## 3. Layout Patterns @@ -52,30 +54,15 @@ Pages normally live within a `DashboardShell` (via `default` layout). Content sh
-
-
- -
-
- - Section Label - -
- - -

- Page Title -

- - -

- Descriptive text goes here. -

-
- - - -
+ + +
diff --git a/frontend/components/common/Breadcrumb.vue b/frontend/components/common/Breadcrumb.vue new file mode 100644 index 0000000..9317d02 --- /dev/null +++ b/frontend/components/common/Breadcrumb.vue @@ -0,0 +1,39 @@ + + + diff --git a/frontend/components/common/PageHeader.vue b/frontend/components/common/PageHeader.vue new file mode 100644 index 0000000..707b723 --- /dev/null +++ b/frontend/components/common/PageHeader.vue @@ -0,0 +1,51 @@ + + + diff --git a/frontend/pages/bundles/[id].vue b/frontend/pages/bundles/[id].vue index ecadf2f..6af5d3a 100644 --- a/frontend/pages/bundles/[id].vue +++ b/frontend/pages/bundles/[id].vue @@ -10,12 +10,10 @@
- +
- +
@@ -118,6 +116,7 @@ From 9820fafe0c62c5a92502548f8d47f12ce3d0973a Mon Sep 17 00:00:00 2001 From: Navid Shad Date: Sun, 1 Feb 2026 15:59:15 +0200 Subject: [PATCH 5/5] refactor: #86ewevg3y Modernize the UI design and styling of various dashboard pages. --- frontend/pages/sessions/index.vue | 279 ++++++------ frontend/pages/sessions/new.vue | 34 +- frontend/pages/settings/subscription.vue | 523 ++++++++++++----------- frontend/pages/statistic.vue | 183 ++++---- 4 files changed, 547 insertions(+), 472 deletions(-) diff --git a/frontend/pages/sessions/index.vue b/frontend/pages/sessions/index.vue index 7f0942b..b89b1e5 100644 --- a/frontend/pages/sessions/index.vue +++ b/frontend/pages/sessions/index.vue @@ -1,156 +1,177 @@ diff --git a/frontend/pages/sessions/new.vue b/frontend/pages/sessions/new.vue index c15fa40..73e86af 100644 --- a/frontend/pages/sessions/new.vue +++ b/frontend/pages/sessions/new.vue @@ -1,14 +1,30 @@ diff --git a/frontend/pages/settings/subscription.vue b/frontend/pages/settings/subscription.vue index d447e05..e90e936 100644 --- a/frontend/pages/settings/subscription.vue +++ b/frontend/pages/settings/subscription.vue @@ -1,290 +1,315 @@ diff --git a/frontend/pages/statistic.vue b/frontend/pages/statistic.vue index b0f5d2e..be21f2f 100644 --- a/frontend/pages/statistic.vue +++ b/frontend/pages/statistic.vue @@ -1,100 +1,113 @@