devskill 2.0.2

package/skills/builderx_api-controllers/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: builderx_api-controllers
+description: Guide to Phoenix Controller structure in builderx_api using FallbackController and standard tuple responses.
+metadata:
+  author: AI Assistant
+  version: "2026.03.23"
+  source: Source code builderx_api
+---
+
+# BuilderX API Controllers
+
+> Conventions for handling HTTP requests and responses at the Web API layer.
+
+## Core
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| FallbackController | Centralized response handling via tuples | [core-fallback](references/core-fallback.md) |
+| Tuple Returns | Standard formats like `{:success, ...}` or `{:failed, ...}` | [core-fallback](references/core-fallback.md) |
+
+## Quick Reference
+
+```elixir
+defmodule BuilderxApiWeb.V1.ExampleController do
+  use BuilderxApiWeb, :controller
+  
+  # Required: Declare action_fallback
+  action_fallback BuilderxApiWeb.FallbackController
+
+  def show(conn, %{"id" => id}) do
+    # Context functions should return tuples compatible with FallbackController instead of standard {:ok, data}
+    # Example:
+    {:success, :with_data, %{id: id, name: "Sample"}}
+  end
+  
+  def delete(conn, _params) do
+    # Return success without data
+    {:success, :success_only}
+  end
+
+  def create(conn, _params) do
+    # Return failure with a custom reason
+    {:failed, :with_reason, "Invalid input data"}
+    
+    # Or return an error from a Changeset validation failure
+    # {:error, changeset}
+  end
+end
+```

package/skills/builderx_api-controllers/references/core-fallback.md

@@ -0,0 +1,62 @@
+---
+name: core-fallback
+description: Standard usage of Action Fallback in Phoenix Controllers of builderx_api.
+---
+
+# Action Fallback in Controllers
+
+Controllers usually do not handle rendering JSON directly. They delegate this responsibility to `BuilderxApiWeb.FallbackController`.
+
+## Mandatory Pattern
+
+Always include the following line at the top of every API controller:
+
+```elixir
+action_fallback BuilderxApiWeb.FallbackController
+```
+
+## Valid Tuple Responses
+
+Every action in an API controller must return one of the following tuples:
+
+1. **Success with data:**
+```elixir
+{:success, :with_data, data}
+# Fallback returns JSON: %{success: true, data: data, fallback: "with_data"}
+```
+
+2. **Success with data wrapped in a custom key:**
+```elixir
+{:success, :with_data, :user_info, data}
+# Fallback returns JSON: %{success: true, fallback: "with_data", user_info: data}
+```
+
+3. **Success without data (only a 200 OK status):**
+```elixir
+{:success, :success_only}
+# Fallback returns JSON: %{success: true, success_only: true}
+```
+
+4. **Failure with a reason:**
+```elixir
+{:failed, :with_reason, "Error description"}
+# Fallback returns JSON (HTTP 422): %{success: false, reason: "Error description", fallback: "with_reason"}
+```
+
+5. **Failure with an error code:**
+```elixir
+{:failed, :with_code, "ERR_7009"}
+# Fallback returns JSON (HTTP 422): %{success: false, code: "ERR_7009", fallback: "with_code"}
+```
+
+6. **Form / Ecto Validation Error:**
+```elixir
+{:error, changeset}
+# Fallback will use ChangesetView to output the corresponding error array (HTTP 422).
+```
+
+7. **Bad Request Error:**
+```elixir
+{:bad_request, :with_reason, "Missing required parameters"}
+# Fallback returns JSON (HTTP 400).
+```

package/skills/builderx_api-schemas/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: builderx_api-schemas
+description: Guidelines for creating Ecto Schemas in builderx_api, including composite primary keys, custom json function and Ecto.Changeset.
+metadata:
+  author: AI Assistant
+  version: "2026.03.23"
+  source: Source code builderx_api
+---
+
+# BuilderX API Schemas
+
+> Conventions and structures for defining Ecto Schemas in the builderx_api project.
+
+## Core
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Schema Definition | Primary keys, site_id attribute, timestamps | [core-schema](references/core-schema.md) |
+| JSON Serialization | Custom `json/1` and `json/2` implementation in Ecto Schema | [core-schema](references/core-schema.md) |
+
+## Quick Reference
+
+```elixir
+defmodule BuilderxApi.Products.Product do
+  use Ecto.Schema
+  import Ecto.Changeset
+
+  alias BuilderxApi.Sites.Site
+
+  @primary_key {:id, :binary_id, autogenerate: true}
+  @foreign_key_type :binary_id
+  @non_required_fields [:id, :inserted_at, :updated_at]
+
+  schema "products" do
+    belongs_to(:site, Site, type: Ecto.UUID, primary_key: true)
+    
+    field :name, :string
+    
+    timestamps(type: :utc_datetime_usec)
+  end
+
+  def changeset(%__MODULE__{} = product, attrs \\ %{}) do
+    fields = __schema__(:fields) -- @non_required_fields
+
+    product
+    |> cast(attrs, fields)
+    |> validate_required([:site_id, :name])
+  end
+
+  # Custom serializer instead of using Phoenix Views
+  def json(%__MODULE__{} = product) do
+    fields = __schema__(:fields)
+    data = Map.take(product, fields)
+
+    data =
+      case Map.fetch(product, :site) do
+        {:ok, %Ecto.Association.NotLoaded{}} ->
+          data
+
+        {:ok, value} ->
+          Map.put(data, :site, Site.json(value))
+
+        _ ->
+          data
+      end
+
+    data
+  end
+
+  def json(products) when is_list(products) do
+    Enum.map(products, &json(&1))
+  end
+
+  def json(_), do: nil
+end
+```

package/skills/builderx_api-schemas/references/core-schema.md

@@ -0,0 +1,78 @@
+---
+name: core-schema
+description: Mandatory configurations when creating Ecto Schemas in builderx_api.
+---
+
+# Core Schema
+
+Standard conventions for declaring a Schema in builderx_api.
+
+## 1. Composite Primary Key
+
+In `builderx_api`, most tables use a composite primary key consisting of `id` and `site_id`. This helps isolate data by site (sharding).
+
+```elixir
+@primary_key {:id, :binary_id, autogenerate: true}
+
+schema "table_name" do
+  belongs_to(:site, Site, type: Ecto.UUID, primary_key: true)
+  # ... other columns
+end
+```
+
+## 2. Timestamps
+
+Use the timestamp type with microseconds precision (`utc_datetime_usec`):
+
+```elixir
+timestamps(type: :utc_datetime_usec)
+```
+
+## 3. JSON Serialization
+
+The project **does not use** Phoenix's `views` directory to render JSON API responses for entities. Instead, each Ecto Schema implements its own `json/1` or `json/2` function to serialize the Ecto struct into a map.
+
+```elixir
+def json(%__MODULE__{} = product) do
+  # Get all declared schema fields
+  fields = __schema__(:fields)
+  data = Map.take(product, fields)
+  
+  # Serialize associations safely if they are loaded
+  data =
+    case Map.fetch(product, :categories) do
+      {:ok, %Ecto.Association.NotLoaded{}} ->
+        data
+
+      {:ok, value} ->
+        Map.put(data, :categories, Category.json(value))
+
+      _ ->
+        data
+    end
+    
+  data
+end
+
+def json(products) when is_list(products) do
+  Enum.map(products, &json(&1))
+end
+
+def json(_), do: nil
+```
+
+## 4. Changeset and Cast Fields
+
+To avoid listing all fields manually when calling `cast/3` in the `changeset`, the project defines a module attribute `@non_required_fields` and subtracts these fields from `__schema__(:fields)`.
+
+```elixir
+@non_required_fields [:id, :inserted_at, :updated_at]
+
+def changeset(%__MODULE__{} = model, attrs \\ %{}) do
+  fields = __schema__(:fields) -- @non_required_fields
+
+  model
+  |> cast(attrs, fields)
+  |> validate_required([:site_id, :name]) # Validate required fields
+end
+```

package/skills/builderx_spa-api/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: builderx_spa-api
+description: Standardized API fetching for BuilderX SPA using useApiget, useApipost, useApiDelete, and useApiProgress from @/composable/fetch. Covers GET/POST requests, file uploads, and progress tracking. Use this skill when making network requests in the builderx_spa project.
+metadata:
+  author: Vũ Lưu
+  version: "2026.3.23"
+  source: Hand-written based on builderx_spa source code
+---
+
+# BuilderX SPA API Wrapper
+
+> Always use the built-in HTTP composables instead of using `axios` directly.
+
+## Core
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Fetching Data | `useApiget`, `useApipost`, `useApiDelete`, `useApiProgress` | [fetch](references/fetch.md) |
+| Class-based API | `BaseApi` class, extending REST controllers in `@/api` | [base-api](references/base-api.md) |
+
+## Quick Reference
+
+### 1. The Class-based API approach (Preferred for CRUD)
+Used when interacting with standard REST resources. Classes exist inside `src/api/` (Core API) and `src/api/landing/` (Landing Page API).
+
+```javascript
+import productApi from '@/api/productApi'
+import landingPageApi from '@/api/landing/pageApi'
+
+// List resources (calls base implementation)
+const res = await productApi.list({ site_id: 123, limit: 10 })
+const landingRes = await landingPageApi.list({ limit: 10 })
+
+
+// Call custom endpoints defined in the child class
+const customRes = await productApi.getProductsBuild({ search: 'shirt' })
+```
+
+### 2. The Composable approach (For one-off requests)
+```javascript
+import { useApiget, useApipost } from '@/composable/fetch'
+
+export default {
+  methods: {
+    async fetchUsers() {
+      const url = `${import.meta.env.VITE_BUILDERX_API_URL}/api/v1/users`
+      // Returns a resolved axios response. Data is usually inside res.data.data
+      const res = await useApiget(url, { page: 1 })
+      console.log(res.data.data)
+    },
+    async saveProfile(payload) {
+      const url = `${import.meta.env.VITE_BUILDERX_API_URL}/api/v1/update_account`
+      // Signature: url, params (query string), body
+      await useApipost(url, null, payload)
+    }
+  }
+}
+```
+
+### File Uploads (No Progress Bar)
+```javascript
+const formData = new FormData()
+formData.append('file', fileObject)
+
+// Provide headers as the 4th argument
+await useApipost(url, null, formData, { 'Content-Type': 'multipart/form-data' })
+```

package/skills/builderx_spa-api/references/base-api.md

@@ -0,0 +1,97 @@
+# Class-based API (`@/api/baseApi.js`)
+
+In `builderx_spa`, while `useApiget` and `useApipost` are convenient, the core CRUD operations and structured resources have dedicated service classes located in the `src/api/` folder.
+
+These classes inherit from `BaseApi`, which automatically manages object URLs, `site_id`, `dashboard` prefixes, and standard REST HTTP calls using a customized `axiosClient`.
+
+## 1. Creating an API Service
+
+When creating a new API service for a resource, extend `BaseApi`. Set the `controller` name to match the backend resource.
+
+```javascript
+// src/api/customerApi.js
+import { BaseApi } from "./baseApi"
+
+class CustomerApi extends BaseApi {
+  constructor() {
+    super({
+      controller: 'customer',
+      v1: true,         // Adds /api/v1/ suffix
+      dashboard: false  // If true, adds /dashboard/ suffix
+    })
+  }
+
+  // You can define custom endpoints bypassing or extending getUrl()
+  getCustomReport(params = {}) {
+    // getUrl options: not_controller, is_dashboard, path
+    const url = this.getUrl(params, { path: '/custom_report' })
+    return this.axios.get(url, { params })
+  }
+}
+
+// Always export a singleton instance
+export default new CustomerApi()
+```
+
+## 2. Dynamic URL Generation
+
+The `getUrl(params)` function inside `BaseApi` automatically analyzes the `params` you pass to construct proper hierarchical URLs:
+
+- If `params.site_id` exists: Injects `/site/:site_id`
+- If `params.page_id` exists: Injects `/:page_id`
+- Appends `/:controller` automatically (unless `not_controller: true` is passed).
+
+## 3. Standard CRUD Methods
+
+`BaseApi` comes with 5 out-of-the-box methods:
+
+```javascript
+import customerApi from '@/api/customerApi'
+
+// 1. list(params) => GET /api/v1[/site/:id]/customer?search=hello
+await customerApi.list({ site_id: 1, search: 'hello' })
+
+// 2. getById(params) => GET /api/v1[/site/:id]/customer/:id
+await customerApi.getById({ id: 123, site_id: 1 })
+
+// 3. create(data) => POST /api/v1[/site/:id]/customer
+await customerApi.create({ site_id: 1, name: 'John Doe' })
+
+// 4. update(data) => PATCH /api/v1[/site/:id]/customer/:id
+await customerApi.update({ id: 123, site_id: 1, name: 'Jane Doe' })
+
+// 5. delete(params) => DELETE /api/v1[/site/:id]/customer/:id
+await customerApi.delete({ id: 123, site_id: 1 })
+```
+
+> **Note:** Just like `useApiget`, all `BaseApi` methods return a Promise resolving to a mapped response: `{ success: true, status: 200, data: {...} }`. The `data` property holds the body payload.
+
+## 4. Landing Page API Variant (`@/api/landing/baseApi.js`)
+
+For the Landing Page module, there is a separate instance of `BaseApi` located inside `src/api/landing/`.
+
+While it shares the same CRUD function names (`list`, `create`, etc.), it operates differently under the hood using `axiosLanding.js`:
+
+1. **Different Base URL**: Uses `import.meta.env.VITE_LANDING_PAGE_API_URL`
+2. **Different Cookies/Auth**: 
+   - Token: `ljwt` instead of `jwt`
+   - Session ID: `lwsid` instead of `wsid`
+   - Extra Headers: `x-team-id` (from `teamset`), `x-org-id` (from `orgset`)
+3. **Simpler URL Routing**: Its `getUrl()` method does NOT attempt to inject `/site/:site_id` or `/dashboard`. It simply appends the `controller` path to its `prefix` (default: `/api/v1/`).
+4. **Subscription Interceptor**: Automatically catches `error_code == 3001` and triggers the `useLandingCheckStore`'s `setRequireSubscription(true)` to prompt the user to upgrade.
+
+```javascript
+// Example: src/api/landing/folderApi.js
+import BaseApi from "./baseApi"
+
+class FolderApi extends BaseApi {
+  constructor() {
+    super({
+      controller: 'folder'
+      // default prefix is '/api/v1/'
+    })
+  }
+}
+
+export default new FolderApi()
+```

package/skills/builderx_spa-api/references/fetch.md

@@ -0,0 +1,70 @@
+# API Fetching (`@/composable/fetch`)
+
+BuilderX SPA wraps `axios` calls to automatically attach the JWT token (`Authorization: Bearer <jwt>`) and the session ID (`x-session-id`). It also uses an in-flight pool mechanism (`flightPool`) to prevent duplicate concurrent requests.
+
+## Text / JSON Data
+
+```js
+import { useApiget, useApipost, useApiDelete } from '@/composable/fetch'
+```
+
+### 1. `useApiget(url, params = null, headers = {})`
+
+Used for `GET` requests.
+- `url`: Full endpoint URL (usually prefixed with `import.meta.env.VITE_BUILDERX_API_URL`).
+- `params`: Object converted to query parameters in the URL (`?key=value`).
+
+### 2. `useApipost(url, params, body, headers = {})`
+
+Used for `POST` requests.
+- `params`: Query parameters (pass `null` if none).
+- `body`: The JSON payload sent in the request body.
+
+### 3. `useApiDelete(url, params, body, headers = {})`
+
+Used for `DELETE` requests. Notice that it accepts a `body` just like `useApipost`.
+
+---
+
+## File Uploads & Progress Tracking
+
+### 1. Standard Upload (No Progress Tracking)
+
+You can use `useApipost` to upload `FormData`. Just make sure to pass `null` for `params` and override the content type headers.
+
+```javascript
+const formData = new FormData()
+formData.append('file', this.selectedFile)
+formData.append('type', 'image')
+
+await useApipost(url, null, formData, { 'Content-Type': 'multipart/form-data' })
+```
+
+### 2. Upload with Progress Bar (`useApiProgress`)
+
+If you need a progress bar, use `useApiProgress`. This function uses raw `XMLHttpRequest` under the hood.
+
+```javascript
+import { useApiProgress } from '@/composable/fetch'
+
+const formData = {
+  file: this.selectedFile,
+  type: 'video'
+}
+
+await useApiProgress(
+  'POST',              // method
+  url,                // url
+  formData,           // payload (automatically grouped into FormData if opts.formData is true)
+  (progressEvent) => { // onProgress callback
+    console.log(`Uploaded ${progressEvent.percent}%`)
+  },
+  { formData: true }  // opts - If false, it gzip compresses JSON instead.
+)
+```
+
+## Rules
+
+- **DO NOT** import `axios` directly in your components or Pinia stores.
+- **DO NOT** manually construct `Authorization` headers. The wrappers handle this via cookies automatically.
+- Always handle errors with `try...catch` or `.catch()` since these return Promises.

package/skills/builderx_spa-design/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: builderx_spa-design
+description: Standardized design system for BuilderX SPA. Covers Typography (text_design.scss), Forms (Input, Select, Checkbox), Layout (Table, Drawer, Modal), and Feedback (Button, Alert). Use this skill to build UI consistently using pre-built components instead of raw HTML/Tailwind.
+metadata:
+  author: Vũ Lưu
+  version: "2026.3.24"
+  source: Hand-written based on @/components/design and text_design.scss
+---
+
+# BuilderX SPA Design System
+
+> ⚠️ **CRITICAL RULE:** Do NOT create custom CSS/SCSS for basic UI elements (text, buttons, inputs, modals). ALWAYS use the components and utility classes documented here.
+
+## Core Concepts
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Typography | Headers, Body text, Colors, utility classes | [core-text-design](references/core-text-design.md) |
+
+## UI Components
+
+We use Ant Design Vue wrapped in custom components to enforce our design language. 
+**Cheat Sheet:** If you need a standard UI element, it likely exists in `@/components/design/[Name].vue` with standard AntD props + our custom props (like `label`, `message` for forms).
+
+| Category | Available Components | Reference |
+|----------|-----------------------|-----------|
+| **Forms & Inputs** | `Input`, `Select`, `Checkbox`, `Radio`, `Switch`, `DatePicker`, `RangePicker` | [features-forms](references/features-forms.md) |
+| **Layout & Data** | `Table`, `Tabs`, `Drawer`, `Modal`, `Sidebar`, `Pagination` | [features-layout-navigation](references/features-layout-navigation.md) |
+| **Actions & Feedback** | `Button`, `Alert`, `Toastify`, `Badge`, `Empty`, `Tooltip` | [features-feedback-actions](references/features-feedback-actions.md) |
+
+## General Usage Rule
+```vue
+<script setup>
+// ALWAYS import from @/components/design, NOT generic antdv
+import { Button, Input, Table } from '@/components/design'
+</script>
+```
+
+## Tailwind CSS Integration
+
+Absolutely **DO NOT** use custom CSS (custom classes in `<style>`) for layout and positioning. Combine the Design Component with **Tailwind CSS** to handle layout, spacing, sizing, and positioning.
+
+**Usage Rules:**
+1. **Design System Components:** Handle the functional logic and core UI/UX attributes (Example: `<Button>` controls color, hover effect, loading state).
+2. **Tailwind CSS:** Handles layout via utility classes (e.g. `flex`, `gap-4`, `p-6`, `col-span-2`), spacing, sizing, and positioning.
+
+### Example Integration:
+
+```vue
+<template>
+  <!-- Use Tailwind classes 'flex', 'gap-4', 'p-6', 'items-center' to design layout -->
+  <div class="flex flex-col gap-4 p-6 bg-white rounded-lg shadow-sm">
+    
+    <div class="flex items-center justify-between">
+      <h2 class="text-design-h3-bold">User Information</h2>
+      <Button type="primary" label="Save Profile" @click="save" />
+    </div>
+
+    <!-- 2-column Grid Layout using Tailwind -->
+    <div class="grid grid-cols-2 gap-4">
+      <!-- Input component scales to its parents grid item -->
+      <Input v-model:value="user.firstName" label="First Name" />
+      <Input v-model:value="user.lastName" label="Last Name" />
+      
+      <!-- Force column spanning -->
+      <Input 
+        class="col-span-2" 
+        v-model:value="user.bio" 
+        label="Biography" 
+        isTextArea 
+      />
+    </div>
+
+  </div>
+</template>
+```
+
+> 💡 **Override Note:** Avoid overwriting internal styles of a Design Component. Before overriding UI, check for available props (such as size, type, or ghost). If you absolutely must override:
+> 1. For small tweaks: Create a custom class and put it in your `<style scoped>` block.
+> 2. For heavy customizations: Create a separate `[name]_custom_design.scss` file and import it, keeping the Vue file clean.
+> **DO NOT** use `/deep/` or `::v-deep` directly on the component tag to brute-force styles.
+

package/skills/builderx_spa-design/references/core-text-design.md

@@ -0,0 +1,64 @@
+---
+name: core-text-design
+description: Typography and color system using text_design.scss
+---
+
+# Typography & Colors
+
+Always use the `.text-design-{level}-{weight}` utility classes or the `<Typography>` component. NEVER write custom `font-size`, `font-weight`, or `color` unless it's a completely unique case.
+
+## 1. Utility Classes (Preferred)
+
+Format: `text-design-[level]-[weight]`
+
+**Levels (from text_design.scss):**
+- `h0` (48px) → `h1` (38px) → `h2` (30px) → `h3` (24px) → `h4` (20px) → `h5` (16px)
+- `body` (14px) → `body-sm` (13px)
+- `footnote` (12px) → `footnote-sm` (10px)
+
+**Weights:**
+- `light` (300), `regular` (400), `medium` (500), `semibold` (600), `bold` (700)
+
+```html
+<!-- Example Usage -->
+<h1 class="text-design-h3-bold text-center">Page Title</h1>
+<p class="text-design-body-regular">Standard paragraph text.</p>
+<span class="text-design-footnote-medium">Small note</span>
+```
+
+## 2. Common Shorthands
+`text_design.scss` provides several hardcoded shorthands with built-in colors:
+
+- `.text-design-body-regular-light` (Muted/818789)
+- `.text-design-link` / `.text-design-link-medium` / `.text-design-link-bold` (Brand color)
+- `.text-design-link-open-medium` (Brand color, underlines on hover)
+- `.text-design-body-neutral` / `.text-design-body-neutral-medium`
+- `.text-design-neutral-strong` (Dark/404946)
+- `.text-design-primary-600-14` (Brand green)
+- `.text-design-white-medium` (White inverse)
+
+## 3. SCSS Mixins
+If you must write SCSS, use the mixins:
+
+```scss
+.my-card-title {
+  @include text-design(h4, bold);
+  color: var(--color-content-brand);
+}
+
+.my-subtitle {
+  @include text-design-body-medium; // Using shorthand mixin
+}
+```
+
+## 4. Typography Component
+```vue
+<script setup>
+import { Typography } from '@/components/design'
+</script>
+<template>
+  <Typography variant="h3" weight="bold" component="span">
+    Hello World
+  </Typography>
+</template>
+```