From 5794b8aa3e82337f6b9f93c7a0c113ca3ea9b394 Mon Sep 17 00:00:00 2001
From: Mina Sameh <mina.sameh.lameh@gmail.com>
Date: Sat, 19 Jul 2025 03:44:29 +0300
Subject: [PATCH 1/3] chore: update .gitignore and add accessibility and code
 style guidelines

- Updated .gitignore to include environment variable files and task management files.
- Added new markdown files for Accessibility, Code Style & Structure, Error Handling & Validation, Forms & Validation, General guidelines, Naming Conventions, Performance Optimization, React + TypeScript Best Practices, State Management, TypeScript Configuration, and UI & Styling.
- These guidelines aim to enhance code quality, maintainability, and accessibility across the AgileSpace project.
---
 .cursor/rules/Accessibility.mdc               | 1435 +++++++++++++++++
 .cursor/rules/Code-Style-Structure.mdc        |  360 +++++
 .cursor/rules/Error-Handling-Validation.mdc   |  626 +++++++
 .cursor/rules/Forms-Validation.mdc            |  583 +++++++
 .cursor/rules/General.mdc                     |  677 ++++++++
 .cursor/rules/Naming-Conventions.mdc          |  553 +++++++
 .cursor/rules/Performance-Optimization.mdc    |  550 +++++++
 .../rules/React-TypeScript-Best-Practices.mdc |  188 +++
 .cursor/rules/State-Management.mdc            |  330 ++++
 .cursor/rules/TypeScript-Configuration.mdc    |  222 +++
 .cursor/rules/UI-Styling.mdc                  |  457 ++++++
 .gitignore                                    |   21 +-
 12 files changed, 5995 insertions(+), 7 deletions(-)
 create mode 100644 .cursor/rules/Accessibility.mdc
 create mode 100644 .cursor/rules/Code-Style-Structure.mdc
 create mode 100644 .cursor/rules/Error-Handling-Validation.mdc
 create mode 100644 .cursor/rules/Forms-Validation.mdc
 create mode 100644 .cursor/rules/General.mdc
 create mode 100644 .cursor/rules/Naming-Conventions.mdc
 create mode 100644 .cursor/rules/Performance-Optimization.mdc
 create mode 100644 .cursor/rules/React-TypeScript-Best-Practices.mdc
 create mode 100644 .cursor/rules/State-Management.mdc
 create mode 100644 .cursor/rules/TypeScript-Configuration.mdc
 create mode 100644 .cursor/rules/UI-Styling.mdc

diff --git a/.cursor/rules/Accessibility.mdc b/.cursor/rules/Accessibility.mdc
new file mode 100644
index 0000000..40e2665
--- /dev/null
+++ b/.cursor/rules/Accessibility.mdc
@@ -0,0 +1,1435 @@
+---
+alwaysApply: true
+---
+
+# Accessibility (a11y) for AgileSpace
+
+## Semantic HTML
+
+### Proper HTML Structure
+
+- Use semantic HTML elements
+- Maintain proper heading hierarchy
+- Use appropriate ARIA landmarks
+- Ensure logical document structure
+
+```tsx
+// ✅ Good - Semantic HTML structure
+export function SessionPage({ spaceId }: { spaceId: string }) {
+  return (
+    <div className="min-h-screen bg-background">
+      <header className="border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
+        <nav className="container flex h-14 items-center">
+          <h1 className="sr-only">AgileSpace Dashboard</h1>
+          <SpaceNavigation spaceId={spaceId} />
+        </nav>
+      </header>
+
+      <main className="container py-6">
+        <section aria-labelledby="sessions-heading">
+          <h2 id="sessions-heading" className="text-2xl font-bold mb-6">
+            Active Sessions
+          </h2>
+          <SessionList spaceId={spaceId} />
+        </section>
+
+        <aside aria-labelledby="stats-heading" className="mt-8">
+          <h3 id="stats-heading" className="text-lg font-semibold mb-4">
+            Session Statistics
+          </h3>
+          <SessionStats spaceId={spaceId} />
+        </aside>
+      </main>
+    </div>
+  );
+}
+```
+
+### Form Accessibility
+
+- Use proper form labels
+- Associate labels with inputs
+- Provide error messages
+- Use appropriate input types
+
+```tsx
+// ✅ Good - Accessible form
+export function AccessibleSessionForm({ onSubmit }: SessionFormProps) {
+  const form = useForm<SessionFormData>({
+    resolver: zodResolver(sessionSchema),
+  });
+
+  return (
+    <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
+      <fieldset>
+        <legend className="text-lg font-semibold mb-4">
+          Session Information
+        </legend>
+
+        <div className="space-y-4">
+          <div>
+            <Label htmlFor="session-title" className="block mb-2">
+              Session Title <span className="text-destructive">*</span>
+            </Label>
+            <Input
+              id="session-title"
+              type="text"
+              {...form.register("title")}
+              aria-describedby="title-error"
+              aria-invalid={!!form.formState.errors.title}
+              placeholder="Enter session title"
+            />
+            {form.formState.errors.title && (
+              <p id="title-error" className="text-sm text-destructive mt-1">
+                {form.formState.errors.title.message}
+              </p>
+            )}
+          </div>
+
+          <div>
+            <Label htmlFor="session-description" className="block mb-2">
+              Description
+            </Label>
+            <Textarea
+              id="session-description"
+              {...form.register("description")}
+              placeholder="Enter session description"
+              aria-describedby="description-help"
+            />
+            <p
+              id="description-help"
+              className="text-sm text-muted-foreground mt-1"
+            >
+              Provide a brief description of what you'll be working on
+            </p>
+          </div>
+        </div>
+      </fieldset>
+
+      <div className="flex items-center justify-end space-x-2">
+        <Button type="submit" disabled={form.formState.isSubmitting}>
+          {form.formState.isSubmitting ? "Creating..." : "Create Session"}
+        </Button>
+      </div>
+    </form>
+  );
+}
+```
+
+## ARIA Attributes
+
+### Proper ARIA Usage
+
+- Use ARIA attributes when HTML semantics aren't sufficient
+- Provide ARIA labels for interactive elements
+- Use ARIA live regions for dynamic content
+- Implement proper ARIA states
+
+```tsx
+// ✅ Good - ARIA attributes
+export function AccessibleButton({
+  children,
+  onClick,
+  disabled,
+  "aria-label": ariaLabel,
+  "aria-describedby": ariaDescribedby,
+  ...props
+}: ButtonProps) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      aria-label={ariaLabel}
+      aria-describedby={ariaDescribedby}
+      aria-disabled={disabled}
+      className={cn(
+        "inline-flex items-center justify-center rounded-md text-sm font-medium",
+        "transition-colors focus-visible:outline-none focus-visible:ring-2",
+        "focus-visible:ring-ring focus-visible:ring-offset-2",
+        "disabled:pointer-events-none disabled:opacity-50",
+        props.className
+      )}
+      {...props}
+    >
+      {children}
+    </button>
+  );
+}
+
+// ✅ Good - ARIA live regions
+export function SessionStatus({ session }: { session: Session }) {
+  const [status, setStatus] = useState(session.status);
+
+  return (
+    <div>
+      <span
+        aria-live="polite"
+        aria-label={`Session status: ${status}`}
+        className="inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium"
+      >
+        {status === "active" && (
+          <>
+            <span className="w-2 h-2 bg-green-500 rounded-full mr-2" />
+            Active
+          </>
+        )}
+        {status === "completed" && (
+          <>
+            <span className="w-2 h-2 bg-blue-500 rounded-full mr-2" />
+            Completed
+          </>
+        )}
+      </span>
+    </div>
+  );
+}
+```
+
+### Complex Widgets
+
+- Implement proper ARIA for custom widgets
+- Use ARIA roles appropriately
+- Provide keyboard navigation
+- Handle focus management
+
+```tsx
+// ✅ Good - Accessible custom widget
+export function AccessibleSelect({
+  options,
+  value,
+  onChange,
+  "aria-label": ariaLabel,
+}: SelectProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [focusedIndex, setFocusedIndex] = useState(-1);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const listboxRef = useRef<HTMLUListElement>(null);
+
+  const handleKeyDown = (event: KeyboardEvent) => {
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault();
+        setFocusedIndex((prev) => (prev < options.length - 1 ? prev + 1 : 0));
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        setFocusedIndex((prev) => (prev > 0 ? prev - 1 : options.length - 1));
+        break;
+      case "Enter":
+      case " ":
+        event.preventDefault();
+        if (focusedIndex >= 0) {
+          onChange(options[focusedIndex].value);
+          setIsOpen(false);
+        }
+        break;
+      case "Escape":
+        setIsOpen(false);
+        triggerRef.current?.focus();
+        break;
+    }
+  };
+
+  return (
+    <div className="relative">
+      <button
+        ref={triggerRef}
+        type="button"
+        aria-haspopup="listbox"
+        aria-expanded={isOpen}
+        aria-label={ariaLabel}
+        onClick={() => setIsOpen(!isOpen)}
+        onKeyDown={handleKeyDown}
+        className="flex items-center justify-between w-full px-3 py-2 border rounded-md"
+      >
+        <span>{options.find((opt) => opt.value === value)?.label}</span>
+        <ChevronDown className="h-4 w-4" />
+      </button>
+
+      {isOpen && (
+        <ul
+          ref={listboxRef}
+          role="listbox"
+          aria-label={ariaLabel}
+          className="absolute z-50 w-full mt-1 bg-background border rounded-md shadow-lg"
+        >
+          {options.map((option, index) => (
+            <li
+              key={option.value}
+              role="option"
+              aria-selected={option.value === value}
+              className={cn(
+                "px-3 py-2 cursor-pointer",
+                focusedIndex === index && "bg-accent",
+                option.value === value && "bg-primary text-primary-foreground"
+              )}
+              onClick={() => {
+                onChange(option.value);
+                setIsOpen(false);
+              }}
+            >
+              {option.label}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+## Keyboard Navigation
+
+### Focus Management
+
+- Ensure logical tab order
+- Provide visible focus indicators
+- Handle focus in modals and dialogs
+- Implement skip links
+
+```tsx
+// ✅ Good - Focus management
+export function AccessibleModal({
+  isOpen,
+  onClose,
+  title,
+  children,
+}: ModalProps) {
+  const modalRef = useRef<HTMLDivElement>(null);
+  const previousFocusRef = useRef<HTMLElement | null>(null);
+
+  useEffect(() => {
+    if (isOpen) {
+      // Store current focus
+      previousFocusRef.current = document.activeElement as HTMLElement;
+
+      // Focus modal
+      modalRef.current?.focus();
+
+      // Trap focus in modal
+      const handleTabKey = (event: KeyboardEvent) => {
+        if (event.key === "Tab") {
+          const focusableElements = modalRef.current?.querySelectorAll(
+            'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+          );
+
+          if (focusableElements) {
+            const firstElement = focusableElements[0] as HTMLElement;
+            const lastElement = focusableElements[
+              focusableElements.length - 1
+            ] as HTMLElement;
+
+            if (event.shiftKey) {
+              if (document.activeElement === firstElement) {
+                event.preventDefault();
+                lastElement.focus();
+              }
+            } else {
+              if (document.activeElement === lastElement) {
+                event.preventDefault();
+                firstElement.focus();
+              }
+            }
+          }
+        }
+      };
+
+      document.addEventListener("keydown", handleTabKey);
+      return () => document.removeEventListener("keydown", handleTabKey);
+    } else {
+      // Restore focus when modal closes
+      previousFocusRef.current?.focus();
+    }
+  }, [isOpen]);
+
+  if (!isOpen) return null;
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center">
+      <div
+        className="fixed inset-0 bg-background/80 backdrop-blur-sm"
+        onClick={onClose}
+      />
+      <div
+        ref={modalRef}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="modal-title"
+        tabIndex={-1}
+        className="relative z-50 w-full max-w-lg rounded-lg border bg-background p-6 shadow-lg"
+      >
+        <div className="flex items-center justify-between mb-4">
+          <h2 id="modal-title" className="text-lg font-semibold">
+            {title}
+          </h2>
+          <button
+            type="button"
+            onClick={onClose}
+            aria-label="Close modal"
+            className="rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2"
+          >
+            <X className="h-4 w-4" />
+          </button>
+        </div>
+        {children}
+      </div>
+    </div>
+  );
+}
+
+// ✅ Good - Skip link
+export function SkipLink() {
+  return (
+    <a
+      href="#main-content"
+      className="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-50 focus:px-4 focus:py-2 focus:bg-background focus:text-foreground focus:border focus:rounded-md"
+    >
+      Skip to main content
+    </a>
+  );
+}
+```
+
+### Keyboard Shortcuts
+
+- Provide keyboard shortcuts for common actions
+- Document shortcuts for users
+- Allow customization of shortcuts
+- Handle conflicts gracefully
+
+```tsx
+// ✅ Good - Keyboard shortcuts
+export function useKeyboardShortcuts() {
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      // Only handle shortcuts when not typing in an input
+      if (
+        event.target instanceof HTMLInputElement ||
+        event.target instanceof HTMLTextAreaElement
+      ) {
+        return;
+      }
+
+      // Ctrl/Cmd + N: New session
+      if ((event.ctrlKey || event.metaKey) && event.key === "n") {
+        event.preventDefault();
+        // Trigger new session action
+      }
+
+      // Ctrl/Cmd + K: Open command palette
+      if ((event.ctrlKey || event.metaKey) && event.key === "k") {
+        event.preventDefault();
+        // Open command palette
+      }
+
+      // Escape: Close modals/dropdowns
+      if (event.key === "Escape") {
+        // Close any open modals or dropdowns
+      }
+    };
+
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, []);
+}
+
+// ✅ Good - Keyboard shortcuts help
+export function KeyboardShortcutsHelp() {
+  return (
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button variant="outline" size="sm">
+          Keyboard Shortcuts
+        </Button>
+      </DialogTrigger>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Keyboard Shortcuts</DialogTitle>
+        </DialogHeader>
+        <div className="space-y-4">
+          <div className="grid grid-cols-2 gap-4 text-sm">
+            <div>
+              <kbd className="px-2 py-1 bg-muted rounded text-xs">
+                Ctrl/Cmd + N
+              </kbd>
+              <span className="ml-2">New session</span>
+            </div>
+            <div>
+              <kbd className="px-2 py-1 bg-muted rounded text-xs">
+                Ctrl/Cmd + K
+              </kbd>
+              <span className="ml-2">Command palette</span>
+            </div>
+            <div>
+              <kbd className="px-2 py-1 bg-muted rounded text-xs">Escape</kbd>
+              <span className="ml-2">Close modal</span>
+            </div>
+          </div>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+## Screen Reader Support
+
+### Screen Reader Announcements
+
+- Use ARIA live regions for dynamic content
+- Provide appropriate announcements
+- Use screen reader only text
+- Handle loading states
+
+```tsx
+// ✅ Good - Screen reader announcements
+export function ScreenReaderAnnouncements() {
+  const [announcement, setAnnouncement] = useState("");
+
+  const announceToScreenReader = (message: string) => {
+    setAnnouncement(message);
+    // Clear announcement after a delay
+    setTimeout(() => setAnnouncement(""), 1000);
+  };
+
+  return (
+    <>
+      {/* Live region for announcements */}
+      <div aria-live="polite" aria-atomic="true" className="sr-only">
+        {announcement}
+      </div>
+
+      {/* Screen reader only content */}
+      <div className="sr-only">
+        <h1>AgileSpace Dashboard</h1>
+        <p>Track your team's work sessions and productivity</p>
+      </div>
+    </>
+  );
+}
+
+// ✅ Good - Loading announcements
+export function LoadingAnnouncement({ isLoading, message }: LoadingProps) {
+  return (
+    <div aria-live="polite" aria-atomic="true" className="sr-only">
+      {isLoading ? `Loading ${message}...` : `${message} loaded`}
+    </div>
+  );
+}
+```
+
+### Alternative Text
+
+- Provide meaningful alt text for images
+- Use descriptive link text
+- Provide text alternatives for icons
+- Handle decorative images
+
+```tsx
+// ✅ Good - Image accessibility
+export function AccessibleImage({
+  src,
+  alt,
+  decorative = false,
+  ...props
+}: ImageProps) {
+  if (decorative) {
+    return <img src={src} alt="" role="presentation" {...props} />;
+  }
+
+  return <img src={src} alt={alt} {...props} />;
+}
+
+// ✅ Good - Icon accessibility
+export function AccessibleIcon({
+  icon: Icon,
+  label,
+  decorative = false,
+  ...props
+}: IconProps) {
+  if (decorative) {
+    return <Icon aria-hidden="true" {...props} />;
+  }
+
+  return <Icon aria-label={label} role="img" {...props} />;
+}
+
+// ✅ Good - Link accessibility
+export function AccessibleLink({
+  href,
+  children,
+  external = false,
+  ...props
+}: LinkProps) {
+  return (
+    <a
+      href={href}
+      {...(external && {
+        target: "_blank",
+        rel: "noopener noreferrer",
+      })}
+      {...props}
+    >
+      {children}
+      {external && <span className="sr-only"> (opens in new tab)</span>}
+    </a>
+  );
+}
+```
+
+## Color and Contrast
+
+### Color Accessibility
+
+- Ensure sufficient color contrast
+- Don't rely solely on color for information
+- Provide alternative indicators
+- Test with color blindness simulators
+
+```tsx
+// ✅ Good - Color accessibility
+export function AccessibleStatusBadge({ status }: { status: string }) {
+  const statusConfig = {
+    active: {
+      className: "bg-green-100 text-green-800 border-green-200",
+      label: "Active",
+      icon: CheckCircle,
+    },
+    completed: {
+      className: "bg-blue-100 text-blue-800 border-blue-200",
+      label: "Completed",
+      icon: Check,
+    },
+    paused: {
+      className: "bg-yellow-100 text-yellow-800 border-yellow-200",
+      label: "Paused",
+      icon: Pause,
+    },
+  };
+
+  const config = statusConfig[status as keyof typeof statusConfig];
+
+  return (
+    <span
+      className={cn(
+        "inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-medium",
+        config.className
+      )}
+      role="status"
+      aria-label={`Status: ${config.label}`}
+    >
+      <config.icon className="mr-1 h-3 w-3" />
+      {config.label}
+    </span>
+  );
+}
+```
+
+### High Contrast Support
+
+- Support high contrast mode
+- Use semantic color tokens
+- Provide alternative themes
+- Test with different contrast settings
+
+```tsx
+// ✅ Good - High contrast support
+export function HighContrastButton({
+  children,
+  variant = "default",
+  ...props
+}: ButtonProps) {
+  return (
+    <button
+      className={cn(
+        "inline-flex items-center justify-center rounded-md text-sm font-medium",
+        "transition-colors focus-visible:outline-none focus-visible:ring-2",
+        "focus-visible:ring-ring focus-visible:ring-offset-2",
+        "disabled:pointer-events-none disabled:opacity-50",
+        // High contrast support
+        "forced-colors:border forced-colors:border-ButtonBorder",
+        variant === "default" &&
+          "bg-primary text-primary-foreground hover:bg-primary/90",
+        variant === "outline" &&
+          "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        props.className
+      )}
+      {...props}
+    >
+      {children}
+    </button>
+  );
+}
+```
+
+## Testing and Validation
+
+### Accessibility Testing
+
+- Use automated testing tools
+- Perform manual testing
+- Test with screen readers
+- Validate ARIA usage
+
+```tsx
+// ✅ Good - Accessibility testing utilities
+export function AccessibilityTestWrapper({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  useEffect(() => {
+    // Check for common accessibility issues
+    const checkAccessibility = () => {
+      // Check for missing alt text
+      const images = document.querySelectorAll("img");
+      images.forEach((img) => {
+        if (!img.alt && !img.getAttribute("aria-hidden")) {
+          console.warn("Image missing alt text:", img);
+        }
+      });
+
+      // Check for proper heading hierarchy
+      const headings = document.querySelectorAll("h1, h2, h3, h4, h5, h6");
+      let previousLevel = 0;
+      headings.forEach((heading) => {
+        const level = parseInt(heading.tagName[1]);
+        if (level > previousLevel + 1) {
+          console.warn("Skipped heading level:", heading);
+        }
+        previousLevel = level;
+      });
+
+      // Check for proper form labels
+      const inputs = document.querySelectorAll("input, select, textarea");
+      inputs.forEach((input) => {
+        const id = input.getAttribute("id");
+        if (id && !document.querySelector(`label[for="${id}"]`)) {
+          console.warn("Input missing label:", input);
+        }
+      });
+    };
+
+    checkAccessibility();
+  }, []);
+
+  return <>{children}</>;
+}
+```
+
+# Accessibility (a11y) for AgileSpace
+
+## Semantic HTML
+
+### Proper HTML Structure
+
+- Use semantic HTML elements
+- Maintain proper heading hierarchy
+- Use appropriate ARIA landmarks
+- Ensure logical document structure
+
+```tsx
+// ✅ Good - Semantic HTML structure
+export function SessionPage({ spaceId }: { spaceId: string }) {
+  return (
+    <div className="min-h-screen bg-background">
+      <header className="border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
+        <nav className="container flex h-14 items-center">
+          <h1 className="sr-only">AgileSpace Dashboard</h1>
+          <SpaceNavigation spaceId={spaceId} />
+        </nav>
+      </header>
+
+      <main className="container py-6">
+        <section aria-labelledby="sessions-heading">
+          <h2 id="sessions-heading" className="text-2xl font-bold mb-6">
+            Active Sessions
+          </h2>
+          <SessionList spaceId={spaceId} />
+        </section>
+
+        <aside aria-labelledby="stats-heading" className="mt-8">
+          <h3 id="stats-heading" className="text-lg font-semibold mb-4">
+            Session Statistics
+          </h3>
+          <SessionStats spaceId={spaceId} />
+        </aside>
+      </main>
+    </div>
+  );
+}
+```
+
+### Form Accessibility
+
+- Use proper form labels
+- Associate labels with inputs
+- Provide error messages
+- Use appropriate input types
+
+```tsx
+// ✅ Good - Accessible form
+export function AccessibleSessionForm({ onSubmit }: SessionFormProps) {
+  const form = useForm<SessionFormData>({
+    resolver: zodResolver(sessionSchema),
+  });
+
+  return (
+    <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
+      <fieldset>
+        <legend className="text-lg font-semibold mb-4">
+          Session Information
+        </legend>
+
+        <div className="space-y-4">
+          <div>
+            <Label htmlFor="session-title" className="block mb-2">
+              Session Title <span className="text-destructive">*</span>
+            </Label>
+            <Input
+              id="session-title"
+              type="text"
+              {...form.register("title")}
+              aria-describedby="title-error"
+              aria-invalid={!!form.formState.errors.title}
+              placeholder="Enter session title"
+            />
+            {form.formState.errors.title && (
+              <p id="title-error" className="text-sm text-destructive mt-1">
+                {form.formState.errors.title.message}
+              </p>
+            )}
+          </div>
+
+          <div>
+            <Label htmlFor="session-description" className="block mb-2">
+              Description
+            </Label>
+            <Textarea
+              id="session-description"
+              {...form.register("description")}
+              placeholder="Enter session description"
+              aria-describedby="description-help"
+            />
+            <p
+              id="description-help"
+              className="text-sm text-muted-foreground mt-1"
+            >
+              Provide a brief description of what you'll be working on
+            </p>
+          </div>
+        </div>
+      </fieldset>
+
+      <div className="flex items-center justify-end space-x-2">
+        <Button type="submit" disabled={form.formState.isSubmitting}>
+          {form.formState.isSubmitting ? "Creating..." : "Create Session"}
+        </Button>
+      </div>
+    </form>
+  );
+}
+```
+
+## ARIA Attributes
+
+### Proper ARIA Usage
+
+- Use ARIA attributes when HTML semantics aren't sufficient
+- Provide ARIA labels for interactive elements
+- Use ARIA live regions for dynamic content
+- Implement proper ARIA states
+
+```tsx
+// ✅ Good - ARIA attributes
+export function AccessibleButton({
+  children,
+  onClick,
+  disabled,
+  "aria-label": ariaLabel,
+  "aria-describedby": ariaDescribedby,
+  ...props
+}: ButtonProps) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      aria-label={ariaLabel}
+      aria-describedby={ariaDescribedby}
+      aria-disabled={disabled}
+      className={cn(
+        "inline-flex items-center justify-center rounded-md text-sm font-medium",
+        "transition-colors focus-visible:outline-none focus-visible:ring-2",
+        "focus-visible:ring-ring focus-visible:ring-offset-2",
+        "disabled:pointer-events-none disabled:opacity-50",
+        props.className
+      )}
+      {...props}
+    >
+      {children}
+    </button>
+  );
+}
+
+// ✅ Good - ARIA live regions
+export function SessionStatus({ session }: { session: Session }) {
+  const [status, setStatus] = useState(session.status);
+
+  return (
+    <div>
+      <span
+        aria-live="polite"
+        aria-label={`Session status: ${status}`}
+        className="inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium"
+      >
+        {status === "active" && (
+          <>
+            <span className="w-2 h-2 bg-green-500 rounded-full mr-2" />
+            Active
+          </>
+        )}
+        {status === "completed" && (
+          <>
+            <span className="w-2 h-2 bg-blue-500 rounded-full mr-2" />
+            Completed
+          </>
+        )}
+      </span>
+    </div>
+  );
+}
+```
+
+### Complex Widgets
+
+- Implement proper ARIA for custom widgets
+- Use ARIA roles appropriately
+- Provide keyboard navigation
+- Handle focus management
+
+```tsx
+// ✅ Good - Accessible custom widget
+export function AccessibleSelect({
+  options,
+  value,
+  onChange,
+  "aria-label": ariaLabel,
+}: SelectProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [focusedIndex, setFocusedIndex] = useState(-1);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const listboxRef = useRef<HTMLUListElement>(null);
+
+  const handleKeyDown = (event: KeyboardEvent) => {
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault();
+        setFocusedIndex((prev) => (prev < options.length - 1 ? prev + 1 : 0));
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        setFocusedIndex((prev) => (prev > 0 ? prev - 1 : options.length - 1));
+        break;
+      case "Enter":
+      case " ":
+        event.preventDefault();
+        if (focusedIndex >= 0) {
+          onChange(options[focusedIndex].value);
+          setIsOpen(false);
+        }
+        break;
+      case "Escape":
+        setIsOpen(false);
+        triggerRef.current?.focus();
+        break;
+    }
+  };
+
+  return (
+    <div className="relative">
+      <button
+        ref={triggerRef}
+        type="button"
+        aria-haspopup="listbox"
+        aria-expanded={isOpen}
+        aria-label={ariaLabel}
+        onClick={() => setIsOpen(!isOpen)}
+        onKeyDown={handleKeyDown}
+        className="flex items-center justify-between w-full px-3 py-2 border rounded-md"
+      >
+        <span>{options.find((opt) => opt.value === value)?.label}</span>
+        <ChevronDown className="h-4 w-4" />
+      </button>
+
+      {isOpen && (
+        <ul
+          ref={listboxRef}
+          role="listbox"
+          aria-label={ariaLabel}
+          className="absolute z-50 w-full mt-1 bg-background border rounded-md shadow-lg"
+        >
+          {options.map((option, index) => (
+            <li
+              key={option.value}
+              role="option"
+              aria-selected={option.value === value}
+              className={cn(
+                "px-3 py-2 cursor-pointer",
+                focusedIndex === index && "bg-accent",
+                option.value === value && "bg-primary text-primary-foreground"
+              )}
+              onClick={() => {
+                onChange(option.value);
+                setIsOpen(false);
+              }}
+            >
+              {option.label}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+## Keyboard Navigation
+
+### Focus Management
+
+- Ensure logical tab order
+- Provide visible focus indicators
+- Handle focus in modals and dialogs
+- Implement skip links
+
+```tsx
+// ✅ Good - Focus management
+export function AccessibleModal({
+  isOpen,
+  onClose,
+  title,
+  children,
+}: ModalProps) {
+  const modalRef = useRef<HTMLDivElement>(null);
+  const previousFocusRef = useRef<HTMLElement | null>(null);
+
+  useEffect(() => {
+    if (isOpen) {
+      // Store current focus
+      previousFocusRef.current = document.activeElement as HTMLElement;
+
+      // Focus modal
+      modalRef.current?.focus();
+
+      // Trap focus in modal
+      const handleTabKey = (event: KeyboardEvent) => {
+        if (event.key === "Tab") {
+          const focusableElements = modalRef.current?.querySelectorAll(
+            'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+          );
+
+          if (focusableElements) {
+            const firstElement = focusableElements[0] as HTMLElement;
+            const lastElement = focusableElements[
+              focusableElements.length - 1
+            ] as HTMLElement;
+
+            if (event.shiftKey) {
+              if (document.activeElement === firstElement) {
+                event.preventDefault();
+                lastElement.focus();
+              }
+            } else {
+              if (document.activeElement === lastElement) {
+                event.preventDefault();
+                firstElement.focus();
+              }
+            }
+          }
+        }
+      };
+
+      document.addEventListener("keydown", handleTabKey);
+      return () => document.removeEventListener("keydown", handleTabKey);
+    } else {
+      // Restore focus when modal closes
+      previousFocusRef.current?.focus();
+    }
+  }, [isOpen]);
+
+  if (!isOpen) return null;
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center">
+      <div
+        className="fixed inset-0 bg-background/80 backdrop-blur-sm"
+        onClick={onClose}
+      />
+      <div
+        ref={modalRef}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="modal-title"
+        tabIndex={-1}
+        className="relative z-50 w-full max-w-lg rounded-lg border bg-background p-6 shadow-lg"
+      >
+        <div className="flex items-center justify-between mb-4">
+          <h2 id="modal-title" className="text-lg font-semibold">
+            {title}
+          </h2>
+          <button
+            type="button"
+            onClick={onClose}
+            aria-label="Close modal"
+            className="rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2"
+          >
+            <X className="h-4 w-4" />
+          </button>
+        </div>
+        {children}
+      </div>
+    </div>
+  );
+}
+
+// ✅ Good - Skip link
+export function SkipLink() {
+  return (
+    <a
+      href="#main-content"
+      className="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-50 focus:px-4 focus:py-2 focus:bg-background focus:text-foreground focus:border focus:rounded-md"
+    >
+      Skip to main content
+    </a>
+  );
+}
+```
+
+### Keyboard Shortcuts
+
+- Provide keyboard shortcuts for common actions
+- Document shortcuts for users
+- Allow customization of shortcuts
+- Handle conflicts gracefully
+
+```tsx
+// ✅ Good - Keyboard shortcuts
+export function useKeyboardShortcuts() {
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      // Only handle shortcuts when not typing in an input
+      if (
+        event.target instanceof HTMLInputElement ||
+        event.target instanceof HTMLTextAreaElement
+      ) {
+        return;
+      }
+
+      // Ctrl/Cmd + N: New session
+      if ((event.ctrlKey || event.metaKey) && event.key === "n") {
+        event.preventDefault();
+        // Trigger new session action
+      }
+
+      // Ctrl/Cmd + K: Open command palette
+      if ((event.ctrlKey || event.metaKey) && event.key === "k") {
+        event.preventDefault();
+        // Open command palette
+      }
+
+      // Escape: Close modals/dropdowns
+      if (event.key === "Escape") {
+        // Close any open modals or dropdowns
+      }
+    };
+
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, []);
+}
+
+// ✅ Good - Keyboard shortcuts help
+export function KeyboardShortcutsHelp() {
+  return (
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button variant="outline" size="sm">
+          Keyboard Shortcuts
+        </Button>
+      </DialogTrigger>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Keyboard Shortcuts</DialogTitle>
+        </DialogHeader>
+        <div className="space-y-4">
+          <div className="grid grid-cols-2 gap-4 text-sm">
+            <div>
+              <kbd className="px-2 py-1 bg-muted rounded text-xs">
+                Ctrl/Cmd + N
+              </kbd>
+              <span className="ml-2">New session</span>
+            </div>
+            <div>
+              <kbd className="px-2 py-1 bg-muted rounded text-xs">
+                Ctrl/Cmd + K
+              </kbd>
+              <span className="ml-2">Command palette</span>
+            </div>
+            <div>
+              <kbd className="px-2 py-1 bg-muted rounded text-xs">Escape</kbd>
+              <span className="ml-2">Close modal</span>
+            </div>
+          </div>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+## Screen Reader Support
+
+### Screen Reader Announcements
+
+- Use ARIA live regions for dynamic content
+- Provide appropriate announcements
+- Use screen reader only text
+- Handle loading states
+
+```tsx
+// ✅ Good - Screen reader announcements
+export function ScreenReaderAnnouncements() {
+  const [announcement, setAnnouncement] = useState("");
+
+  const announceToScreenReader = (message: string) => {
+    setAnnouncement(message);
+    // Clear announcement after a delay
+    setTimeout(() => setAnnouncement(""), 1000);
+  };
+
+  return (
+    <>
+      {/* Live region for announcements */}
+      <div aria-live="polite" aria-atomic="true" className="sr-only">
+        {announcement}
+      </div>
+
+      {/* Screen reader only content */}
+      <div className="sr-only">
+        <h1>AgileSpace Dashboard</h1>
+        <p>Track your team's work sessions and productivity</p>
+      </div>
+    </>
+  );
+}
+
+// ✅ Good - Loading announcements
+export function LoadingAnnouncement({ isLoading, message }: LoadingProps) {
+  return (
+    <div aria-live="polite" aria-atomic="true" className="sr-only">
+      {isLoading ? `Loading ${message}...` : `${message} loaded`}
+    </div>
+  );
+}
+```
+
+### Alternative Text
+
+- Provide meaningful alt text for images
+- Use descriptive link text
+- Provide text alternatives for icons
+- Handle decorative images
+
+```tsx
+// ✅ Good - Image accessibility
+export function AccessibleImage({
+  src,
+  alt,
+  decorative = false,
+  ...props
+}: ImageProps) {
+  if (decorative) {
+    return <img src={src} alt="" role="presentation" {...props} />;
+  }
+
+  return <img src={src} alt={alt} {...props} />;
+}
+
+// ✅ Good - Icon accessibility
+export function AccessibleIcon({
+  icon: Icon,
+  label,
+  decorative = false,
+  ...props
+}: IconProps) {
+  if (decorative) {
+    return <Icon aria-hidden="true" {...props} />;
+  }
+
+  return <Icon aria-label={label} role="img" {...props} />;
+}
+
+// ✅ Good - Link accessibility
+export function AccessibleLink({
+  href,
+  children,
+  external = false,
+  ...props
+}: LinkProps) {
+  return (
+    <a
+      href={href}
+      {...(external && {
+        target: "_blank",
+        rel: "noopener noreferrer",
+      })}
+      {...props}
+    >
+      {children}
+      {external && <span className="sr-only"> (opens in new tab)</span>}
+    </a>
+  );
+}
+```
+
+## Color and Contrast
+
+### Color Accessibility
+
+- Ensure sufficient color contrast
+- Don't rely solely on color for information
+- Provide alternative indicators
+- Test with color blindness simulators
+
+```tsx
+// ✅ Good - Color accessibility
+export function AccessibleStatusBadge({ status }: { status: string }) {
+  const statusConfig = {
+    active: {
+      className: "bg-green-100 text-green-800 border-green-200",
+      label: "Active",
+      icon: CheckCircle,
+    },
+    completed: {
+      className: "bg-blue-100 text-blue-800 border-blue-200",
+      label: "Completed",
+      icon: Check,
+    },
+    paused: {
+      className: "bg-yellow-100 text-yellow-800 border-yellow-200",
+      label: "Paused",
+      icon: Pause,
+    },
+  };
+
+  const config = statusConfig[status as keyof typeof statusConfig];
+
+  return (
+    <span
+      className={cn(
+        "inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-medium",
+        config.className
+      )}
+      role="status"
+      aria-label={`Status: ${config.label}`}
+    >
+      <config.icon className="mr-1 h-3 w-3" />
+      {config.label}
+    </span>
+  );
+}
+```
+
+### High Contrast Support
+
+- Support high contrast mode
+- Use semantic color tokens
+- Provide alternative themes
+- Test with different contrast settings
+
+```tsx
+// ✅ Good - High contrast support
+export function HighContrastButton({
+  children,
+  variant = "default",
+  ...props
+}: ButtonProps) {
+  return (
+    <button
+      className={cn(
+        "inline-flex items-center justify-center rounded-md text-sm font-medium",
+        "transition-colors focus-visible:outline-none focus-visible:ring-2",
+        "focus-visible:ring-ring focus-visible:ring-offset-2",
+        "disabled:pointer-events-none disabled:opacity-50",
+        // High contrast support
+        "forced-colors:border forced-colors:border-ButtonBorder",
+        variant === "default" &&
+          "bg-primary text-primary-foreground hover:bg-primary/90",
+        variant === "outline" &&
+          "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        props.className
+      )}
+      {...props}
+    >
+      {children}
+    </button>
+  );
+}
+```
+
+## Testing and Validation
+
+### Accessibility Testing
+
+- Use automated testing tools
+- Perform manual testing
+- Test with screen readers
+- Validate ARIA usage
+
+```tsx
+// ✅ Good - Accessibility testing utilities
+export function AccessibilityTestWrapper({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  useEffect(() => {
+    // Check for common accessibility issues
+    const checkAccessibility = () => {
+      // Check for missing alt text
+      const images = document.querySelectorAll("img");
+      images.forEach((img) => {
+        if (!img.alt && !img.getAttribute("aria-hidden")) {
+          console.warn("Image missing alt text:", img);
+        }
+      });
+
+      // Check for proper heading hierarchy
+      const headings = document.querySelectorAll("h1, h2, h3, h4, h5, h6");
+      let previousLevel = 0;
+      headings.forEach((heading) => {
+        const level = parseInt(heading.tagName[1]);
+        if (level > previousLevel + 1) {
+          console.warn("Skipped heading level:", heading);
+        }
+        previousLevel = level;
+      });
+
+      // Check for proper form labels
+      const inputs = document.querySelectorAll("input, select, textarea");
+      inputs.forEach((input) => {
+        const id = input.getAttribute("id");
+        if (id && !document.querySelector(`label[for="${id}"]`)) {
+          console.warn("Input missing label:", input);
+        }
+      });
+    };
+
+    checkAccessibility();
+  }, []);
+
+  return <>{children}</>;
+}
+```
diff --git a/.cursor/rules/Code-Style-Structure.mdc b/.cursor/rules/Code-Style-Structure.mdc
new file mode 100644
index 0000000..c3cbc51
--- /dev/null
+++ b/.cursor/rules/Code-Style-Structure.mdc
@@ -0,0 +1,360 @@
+---
+alwaysApply: true
+---
+
+# Code Style & Structure for AgileSpace
+
+## Code Style Standards
+
+### Formatting
+
+- 2-space indentation
+- Single quotes (except to avoid escaping)
+- No semicolons (unless disambiguation requires)
+- No unused variables
+- Space after keywords (if (...))
+- Space before function's (
+- Always use === / !==
+- Operators spaced (a + b)
+- Commas followed by space
+- else on same line as closing }
+- Multi-line if blocks always use { }
+
+```tsx
+// ✅ Good - Proper formatting
+function formatDuration(startTime: string, endTime?: string): string {
+  if (!endTime) {
+    return "In progress";
+  }
+
+  const duration = new Date(endTime).getTime() - new Date(startTime).getTime();
+  const minutes = Math.floor(duration / 1000 / 60);
+
+  return `${minutes} minutes`;
+}
+
+// ✅ Good - Proper spacing
+const isActive = session.status === "active";
+const totalTime = startTime + endTime;
+const sessionData = {
+  id: sessionId,
+  title: sessionTitle,
+  description: sessionDescription,
+};
+```
+
+### Naming Conventions
+
+- camelCase for variables/functions
+- PascalCase for components and interfaces
+- Use descriptive names with auxiliary verbs (e.g., isLoading, hasError)
+- Prefix boolean variables with is/has/can/should
+
+```tsx
+// ✅ Good - Descriptive naming
+const isLoading = query.isLoading;
+const hasError = query.error !== null;
+const canEdit = user.permissions.includes("edit");
+const shouldShowTimer = session.status === "active";
+
+// ✅ Good - Component naming
+interface SessionCardProps {
+  session: Session;
+  onEndSession: (sessionId: string) => void;
+}
+
+export function SessionCard({ session, onEndSession }: SessionCardProps) {
+  // Component implementation
+}
+```
+
+## File Structure
+
+### Component Files
+
+- One component per file
+- Export the main component as default or named export
+- File layout: exported component → subcomponents → hooks/helpers → static content
+
+```tsx
+// ✅ Good - Component file structure
+// 1. Imports
+import { useState, useCallback } from "react";
+import { Card, CardHeader, CardTitle } from "@/components/ui/card";
+import { Button } from "@/components/ui/button";
+import { useSessionsApi } from "@/hooks/api/use-sessions";
+
+// 2. Types
+interface SessionCardProps {
+  session: Session;
+  onEndSession?: (sessionId: string) => void;
+}
+
+// 3. Main component
+export function SessionCard({ session, onEndSession }: SessionCardProps) {
+  // Component implementation
+}
+
+// 4. Subcomponents (if any)
+function SessionTimer({ sessionId }: { sessionId: string }) {
+  // Timer implementation
+}
+
+// 5. Helper functions
+function formatDuration(startTime: string, endTime?: string): string {
+  // Formatting logic
+}
+
+// 6. Constants
+const TIMER_UPDATE_INTERVAL = 1000;
+```
+
+### Hook Files
+
+- Use `use-*` prefix for custom hooks
+- Use `use-*-api` prefix for data fetching hooks
+- Export hooks as named exports
+- Group related hooks in the same file
+
+```tsx
+// ✅ Good - Hook file structure
+// hooks/use-sessions.ts
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { supabase } from "@/lib/supabase/client";
+
+export function useSessionsApi(spaceId: string) {
+  return useQuery({
+    queryKey: ["sessions", spaceId],
+    queryFn: () => getSessions(spaceId),
+  });
+}
+
+export function useCreateSessionApi() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: createSession,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["sessions"] });
+    },
+  });
+}
+
+// Helper functions
+async function getSessions(spaceId: string): Promise<Session[]> {
+  const { data, error } = await supabase
+    .from("sessions")
+    .select("*")
+    .eq("space_id", spaceId);
+
+  if (error) throw error;
+  return data;
+}
+```
+
+## Functional Patterns
+
+### Functional Programming
+
+- Use functional, declarative patterns
+- Avoid classes (use functional components)
+- Favor pure functions
+- Use array methods over loops when possible
+
+```tsx
+// ✅ Good - Functional patterns
+const activeSessions = sessions.filter((session) => !session.end_time);
+const sessionDurations = sessions.map((session) => ({
+  id: session.id,
+  duration: calculateDuration(session.start_time, session.end_time),
+}));
+
+const totalDuration = sessionDurations.reduce(
+  (total, session) => total + session.duration,
+  0
+);
+
+// ✅ Good - Pure functions
+function calculateDuration(startTime: string, endTime?: string): number {
+  if (!endTime) return 0;
+  return new Date(endTime).getTime() - new Date(startTime).getTime();
+}
+```
+
+### Helper Functions
+
+- Extract reusable logic into helper functions
+- Keep functions small and focused
+- Use descriptive function names
+- Group related functions in utility files
+
+```tsx
+// ✅ Good - Helper functions
+// lib/utils.ts
+export function cn(...classes: (string | undefined | null | false)[]): string {
+  return classes.filter(Boolean).join(" ");
+}
+
+export function formatDate(date: string | Date): string {
+  return new Intl.DateTimeFormat("en-US", {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  }).format(new Date(date));
+}
+
+export function debounce<T extends (...args: any[]) => any>(
+  func: T,
+  wait: number
+): (...args: Parameters<T>) => void {
+  let timeout: NodeJS.Timeout;
+  return (...args: Parameters<T>) => {
+    clearTimeout(timeout);
+    timeout = setTimeout(() => func(...args), wait);
+  };
+}
+```
+
+## Error Handling
+
+### Guard Clauses
+
+- Validate inputs and preconditions early
+- Use guard clauses for error handling
+- Place happy-path logic last
+
+```tsx
+// ✅ Good - Guard clauses
+function processSession(session: Session | null): string {
+  if (!session) {
+    return "No session provided";
+  }
+
+  if (!session.title) {
+    return "Session has no title";
+  }
+
+  if (
+    session.end_time &&
+    new Date(session.end_time) < new Date(session.start_time)
+  ) {
+    return "Invalid session duration";
+  }
+
+  // Happy path
+  return `Session: ${session.title}`;
+}
+```
+
+### Error Boundaries
+
+- Implement error boundaries for component error handling
+- Provide clear, user-friendly error messages
+- Log or report unexpected errors
+
+```tsx
+// ✅ Good - Error boundary
+export function ErrorBoundary({ children }: { children: React.ReactNode }) {
+  return (
+    <ErrorBoundary
+      fallback={({ error, resetErrorBoundary }) => (
+        <div className="p-4 border border-red-200 rounded-lg bg-red-50">
+          <h2 className="text-lg font-semibold text-red-800">
+            Something went wrong
+          </h2>
+          <p className="text-red-600 mt-2">{error.message}</p>
+          <Button onClick={resetErrorBoundary} className="mt-4">
+            Try again
+          </Button>
+        </div>
+      )}
+    >
+      {children}
+    </ErrorBoundary>
+  );
+}
+```
+
+## Code Organization
+
+### Import Organization
+
+- Group imports by type and source
+- Use absolute imports for project files
+- Use relative imports for closely related files
+
+```tsx
+// ✅ Good - Import organization
+// 1. React and external libraries
+import { useState, useEffect, useCallback } from "react";
+import { useQuery, useMutation } from "@tanstack/react-query";
+
+// 2. UI components
+import { Button } from "@/components/ui/button";
+import { Card, CardHeader, CardTitle } from "@/components/ui/card";
+
+// 3. Custom hooks
+import { useSessionsApi } from "@/hooks/api/use-sessions";
+
+// 4. Utilities and types
+import { cn, formatDate } from "@/lib/utils";
+import type { Session } from "@/types";
+
+// 5. Relative imports (if any)
+import { SessionTimer } from "./session-timer";
+```
+
+### File Naming
+
+- Use kebab-case for file names
+- Use descriptive names that indicate purpose
+- Group related files in directories
+
+```
+src/
+├── components/
+│   ├── session-card.tsx
+│   ├── session-timer.tsx
+│   └── session-list.tsx
+├── hooks/
+│   ├── use-sessions.ts
+│   ├── use-sessions-api.ts
+│   └── use-session-timer.ts
+└── lib/
+    ├── supabase/
+    │   ├── client.ts
+    │   ├── queries.ts
+    │   └── mutations.ts
+    └── utils.ts
+```
+
+## Performance Considerations
+
+### Code Splitting
+
+- Use React.lazy for route-based code splitting
+- Split large components into smaller pieces
+- Use dynamic imports for heavy dependencies
+
+```tsx
+// ✅ Good - Code splitting
+const SessionChart = lazy(() => import("./session-chart"));
+const SessionReport = lazy(() => import("./session-report"));
+
+// ✅ Good - Dynamic imports
+const heavyLibrary = await import("heavy-charting-library");
+```
+
+### Bundle Optimization
+
+- Structure modules for effective tree-shaking
+- Avoid importing entire libraries
+- Use named imports when possible
+
+```tsx
+// ✅ Good - Named imports
+import { Card, CardHeader, CardTitle } from "@/components/ui/card";
+
+// ❌ Avoid - Importing entire library
+import * as UI from "@/components/ui";
+```
diff --git a/.cursor/rules/Error-Handling-Validation.mdc b/.cursor/rules/Error-Handling-Validation.mdc
new file mode 100644
index 0000000..7f046d2
--- /dev/null
+++ b/.cursor/rules/Error-Handling-Validation.mdc
@@ -0,0 +1,626 @@
+---
+alwaysApply: true
+---
+
+# Error Handling & Validation for AgileSpace
+
+## Input Validation
+
+### Guard Clauses
+
+- Validate inputs and preconditions early
+- Use guard clauses for error handling
+- Place happy-path logic last
+- Provide clear error messages
+
+```tsx
+// ✅ Good - Guard clauses
+function processSession(session: Session | null): string {
+  if (!session) {
+    return "No session provided";
+  }
+
+  if (!session.title) {
+    return "Session has no title";
+  }
+
+  if (
+    session.end_time &&
+    new Date(session.end_time) < new Date(session.start_time)
+  ) {
+    return "Invalid session duration";
+  }
+
+  // Happy path
+  return `Session: ${session.title}`;
+}
+
+// ✅ Good - Function with validation
+function createSession(data: SessionFormData): Promise<Session> {
+  // Validate required fields
+  if (!data.title?.trim()) {
+    throw new Error("Session title is required");
+  }
+
+  if (data.title.length > 100) {
+    throw new Error("Session title must be less than 100 characters");
+  }
+
+  if (data.estimated_duration && data.estimated_duration < 1) {
+    throw new Error("Estimated duration must be at least 1 minute");
+  }
+
+  // Happy path
+  return supabase.from("sessions").insert(data).select().single();
+}
+```
+
+### Schema Validation
+
+- Use zod for runtime validation
+- Define schemas for all data structures
+- Provide meaningful error messages
+- Handle validation errors gracefully
+
+```tsx
+// ✅ Good - Comprehensive validation schema
+import { z } from "zod";
+
+const sessionSchema = z.object({
+  title: z
+    .string()
+    .min(1, "Title is required")
+    .max(100, "Title must be less than 100 characters")
+    .trim(),
+
+  description: z
+    .string()
+    .max(500, "Description must be less than 500 characters")
+    .optional(),
+
+  track_id: z.string().uuid("Invalid track ID").optional(),
+
+  tags: z.array(z.string()).max(10, "Maximum 10 tags allowed").optional(),
+
+  estimated_duration: z
+    .number()
+    .min(1, "Duration must be at least 1 minute")
+    .max(480, "Duration cannot exceed 8 hours")
+    .optional(),
+});
+
+const userProfileSchema = z.object({
+  name: z
+    .string()
+    .min(2, "Name must be at least 2 characters")
+    .max(50, "Name must be less than 50 characters")
+    .regex(/^[a-zA-Z\s]+$/, "Name can only contain letters and spaces"),
+
+  email: z
+    .string()
+    .email("Please enter a valid email address")
+    .min(1, "Email is required"),
+
+  timezone: z.string().min(1, "Timezone is required"),
+
+  working_hours: z
+    .object({
+      start: z
+        .string()
+        .regex(/^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$/, "Invalid time format"),
+      end: z
+        .string()
+        .regex(/^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$/, "Invalid time format"),
+    })
+    .refine(
+      (data) => {
+        const start = new Date(`2000-01-01T${data.start}`);
+        const end = new Date(`2000-01-01T${data.end}`);
+        return start < end;
+      },
+      {
+        message: "End time must be after start time",
+        path: ["end"],
+      }
+    ),
+});
+
+type SessionFormData = z.infer<typeof sessionSchema>;
+type UserProfileFormData = z.infer<typeof userProfileSchema>;
+```
+
+## Error Handling Patterns
+
+### Try-Catch Blocks
+
+- Use try-catch for async operations
+- Handle specific error types
+- Provide fallback behavior
+- Log errors appropriately
+
+```tsx
+// ✅ Good - Error handling with try-catch
+async function createSessionWithErrorHandling(
+  data: SessionFormData
+): Promise<ApiResponse<Session>> {
+  try {
+    // Validate input
+    const validatedData = sessionSchema.parse(data);
+
+    // Attempt to create session
+    const { data: session, error } = await supabase
+      .from("sessions")
+      .insert(validatedData)
+      .select()
+      .single();
+
+    if (error) {
+      throw new Error(error.message);
+    }
+
+    return { success: true, data: session };
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return {
+        success: false,
+        error: "Validation failed",
+        details: error.errors.map((err) => ({
+          field: err.path.join("."),
+          message: err.message,
+        })),
+      };
+    }
+
+    if (error instanceof Error) {
+      console.error("Session creation failed:", error.message);
+      return {
+        success: false,
+        error: "Failed to create session. Please try again.",
+      };
+    }
+
+    return {
+      success: false,
+      error: "An unexpected error occurred",
+    };
+  }
+}
+```
+
+### Error Boundaries
+
+- Implement error boundaries for component errors
+- Provide fallback UI
+- Log errors for debugging
+- Allow error recovery
+
+```tsx
+// ✅ Good - Error boundary component
+import { Component, ReactNode } from "react";
+
+interface ErrorBoundaryState {
+  hasError: boolean;
+  error?: Error;
+}
+
+interface ErrorBoundaryProps {
+  children: ReactNode;
+  fallback?: ReactNode;
+  onError?: (error: Error, errorInfo: any) => void;
+}
+
+export class ErrorBoundary extends Component<
+  ErrorBoundaryProps,
+  ErrorBoundaryState
+> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: any) {
+    console.error("Error caught by boundary:", error, errorInfo);
+
+    // Log to error reporting service
+    if (process.env.NODE_ENV === "production") {
+      // Send to error reporting service
+    }
+
+    this.props.onError?.(error, errorInfo);
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return (
+        this.props.fallback || (
+          <div className="p-4 border border-red-200 rounded-lg bg-red-50">
+            <h2 className="text-lg font-semibold text-red-800 mb-2">
+              Something went wrong
+            </h2>
+            <p className="text-red-600 mb-4">
+              {this.state.error?.message || "An unexpected error occurred"}
+            </p>
+            <button
+              onClick={() =>
+                this.setState({ hasError: false, error: undefined })
+              }
+              className="px-4 py-2 bg-red-600 text-white rounded hover:bg-red-700"
+            >
+              Try again
+            </button>
+          </div>
+        )
+      );
+    }
+
+    return this.props.children;
+  }
+}
+```
+
+## API Error Handling
+
+### TanStack Query Error Handling
+
+- Handle query and mutation errors
+- Provide user-friendly error messages
+- Implement retry logic
+- Show appropriate loading states
+
+```tsx
+// ✅ Good - Query error handling
+export function useSessionsWithErrorHandling(spaceId: string) {
+  const query = useQuery({
+    queryKey: ["sessions", spaceId],
+    queryFn: () => getSessions(spaceId),
+    retry: (failureCount, error) => {
+      // Don't retry on 4xx errors
+      if (error instanceof Error && error.message.includes("404")) {
+        return false;
+      }
+      return failureCount < 3;
+    },
+    retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
+  });
+
+  return {
+    ...query,
+    errorMessage: query.error ? getErrorMessage(query.error) : null,
+  };
+}
+
+// ✅ Good - Mutation error handling
+export function useCreateSessionWithErrorHandling() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: createSession,
+    onError: (error, variables, context) => {
+      console.error("Session creation failed:", error);
+
+      // Show user-friendly error message
+      toast.error(getErrorMessage(error));
+
+      // Revert optimistic update if needed
+      if (context?.previousSessions) {
+        queryClient.setQueryData(
+          ["sessions", variables.space_id],
+          context.previousSessions
+        );
+      }
+    },
+    onSuccess: (newSession) => {
+      toast.success("Session created successfully");
+      queryClient.invalidateQueries({ queryKey: ["sessions"] });
+    },
+  });
+}
+
+// ✅ Good - Error message utility
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    // Handle specific error types
+    if (error.message.includes("Network")) {
+      return "Network error. Please check your connection and try again.";
+    }
+
+    if (error.message.includes("401")) {
+      return "You are not authorized to perform this action.";
+    }
+
+    if (error.message.includes("403")) {
+      return "You do not have permission to perform this action.";
+    }
+
+    if (error.message.includes("404")) {
+      return "The requested resource was not found.";
+    }
+
+    if (error.message.includes("429")) {
+      return "Too many requests. Please wait a moment and try again.";
+    }
+
+    if (error.message.includes("500")) {
+      return "Server error. Please try again later.";
+    }
+
+    return error.message;
+  }
+
+  return "An unexpected error occurred";
+}
+```
+
+## Form Validation
+
+### Client-Side Validation
+
+- Validate on blur and submit
+- Show immediate feedback
+- Use appropriate validation rules
+- Handle async validation
+
+```tsx
+// ✅ Good - Form validation with react-hook-form
+export function SessionFormWithValidation({ onSubmit }: SessionFormProps) {
+  const form = useForm<SessionFormData>({
+    resolver: zodResolver(sessionSchema),
+    mode: "onBlur", // Validate on blur
+    defaultValues: {
+      title: "",
+      description: "",
+      tags: [],
+    },
+  });
+
+  const handleSubmit = form.handleSubmit(async (data) => {
+    try {
+      await onSubmit(data);
+      form.reset();
+    } catch (error) {
+      // Handle submission errors
+      if (error instanceof z.ZodError) {
+        error.errors.forEach((err) => {
+          form.setError(err.path.join(".") as any, {
+            type: "server",
+            message: err.message,
+          });
+        });
+      } else {
+        toast.error("Failed to create session. Please try again.");
+      }
+    }
+  });
+
+  return (
+    <form onSubmit={handleSubmit} className="space-y-6">
+      <div className="space-y-2">
+        <Label htmlFor="title">Session Title *</Label>
+        <Input
+          id="title"
+          {...form.register("title")}
+          placeholder="Enter session title"
+          className={cn(form.formState.errors.title && "border-destructive")}
+          aria-describedby={
+            form.formState.errors.title ? "title-error" : undefined
+          }
+          aria-invalid={!!form.formState.errors.title}
+        />
+        {form.formState.errors.title && (
+          <p id="title-error" className="text-sm text-destructive">
+            {form.formState.errors.title.message}
+          </p>
+        )}
+      </div>
+
+      <div className="space-y-2">
+        <Label htmlFor="description">Description</Label>
+        <Textarea
+          id="description"
+          {...form.register("description")}
+          placeholder="Enter session description"
+          className="min-h-[100px]"
+        />
+        {form.formState.errors.description && (
+          <p className="text-sm text-destructive">
+            {form.formState.errors.description.message}
+          </p>
+        )}
+      </div>
+
+      <Button
+        type="submit"
+        disabled={form.formState.isSubmitting}
+        className="w-full"
+      >
+        {form.formState.isSubmitting ? "Creating..." : "Create Session"}
+      </Button>
+    </form>
+  );
+}
+```
+
+### Server-Side Validation
+
+- Always validate on the server
+- Use the same schemas for consistency
+- Return structured error responses
+- Handle validation errors gracefully
+
+```tsx
+// ✅ Good - Server-side validation
+export async function validateAndCreateSession(
+  data: unknown
+): Promise<ApiResponse<Session>> {
+  try {
+    // Validate input
+    const validatedData = sessionSchema.parse(data);
+
+    // Check business rules
+    const existingSession = await supabase
+      .from("sessions")
+      .select("id")
+      .eq("member_id", validatedData.member_id)
+      .is("end_time", null)
+      .single();
+
+    if (existingSession.data) {
+      return {
+        success: false,
+        error: "You already have an active session. Please end it first.",
+      };
+    }
+
+    // Create session
+    const { data: session, error } = await supabase
+      .from("sessions")
+      .insert(validatedData)
+      .select()
+      .single();
+
+    if (error) {
+      throw new Error(error.message);
+    }
+
+    return { success: true, data: session };
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return {
+        success: false,
+        error: "Validation failed",
+        details: error.errors.map((err) => ({
+          field: err.path.join("."),
+          message: err.message,
+        })),
+      };
+    }
+
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "An error occurred",
+    };
+  }
+}
+```
+
+## Error Recovery
+
+### Retry Logic
+
+- Implement exponential backoff
+- Limit retry attempts
+- Handle different error types
+- Provide user feedback
+
+```tsx
+// ✅ Good - Retry logic
+export function useRetryableMutation<TData, TVariables>(
+  mutationFn: (variables: TVariables) => Promise<TData>,
+  options: {
+    maxRetries?: number;
+    retryDelay?: number;
+    onError?: (error: Error, attempt: number) => void;
+  } = {}
+) {
+  const { maxRetries = 3, retryDelay = 1000, onError } = options;
+  const [attempt, setAttempt] = useState(0);
+  const [isRetrying, setIsRetrying] = useState(false);
+
+  const executeWithRetry = useCallback(
+    async (variables: TVariables): Promise<TData> => {
+      let lastError: Error;
+
+      for (let i = 0; i <= maxRetries; i++) {
+        try {
+          setAttempt(i);
+          setIsRetrying(i > 0);
+
+          const result = await mutationFn(variables);
+          setIsRetrying(false);
+          return result;
+        } catch (error) {
+          lastError =
+            error instanceof Error ? error : new Error("Unknown error");
+
+          if (i === maxRetries) {
+            setIsRetrying(false);
+            throw lastError;
+          }
+
+          onError?.(lastError, i);
+
+          // Exponential backoff
+          const delay = retryDelay * Math.pow(2, i);
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+      }
+
+      throw lastError!;
+    },
+    [mutationFn, maxRetries, retryDelay, onError]
+  );
+
+  return {
+    executeWithRetry,
+    attempt,
+    isRetrying,
+  };
+}
+```
+
+### Error Reporting
+
+- Log errors appropriately
+- Send errors to monitoring service
+- Include context information
+- Respect user privacy
+
+```tsx
+// ✅ Good - Error reporting
+export function reportError(error: Error, context?: Record<string, any>) {
+  const errorInfo = {
+    message: error.message,
+    stack: error.stack,
+    timestamp: new Date().toISOString(),
+    url: window.location.href,
+    userAgent: navigator.userAgent,
+    context,
+  };
+
+  // Log to console in development
+  if (process.env.NODE_ENV === "development") {
+    console.error("Error reported:", errorInfo);
+  }
+
+  // Send to error reporting service in production
+  if (process.env.NODE_ENV === "production") {
+    // Send to error reporting service (e.g., Sentry, LogRocket)
+    // This would be implemented based on your error reporting service
+    console.error("Error would be sent to reporting service:", errorInfo);
+  }
+}
+
+// ✅ Good - Error boundary with reporting
+export function ErrorBoundaryWithReporting({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <ErrorBoundary
+      onError={(error, errorInfo) => {
+        reportError(error, {
+          componentStack: errorInfo.componentStack,
+          errorBoundary: true,
+        });
+      }}
+    >
+      {children}
+    </ErrorBoundary>
+  );
+}
+```
diff --git a/.cursor/rules/Forms-Validation.mdc b/.cursor/rules/Forms-Validation.mdc
new file mode 100644
index 0000000..4351001
--- /dev/null
+++ b/.cursor/rules/Forms-Validation.mdc
@@ -0,0 +1,583 @@
+---
+alwaysApply: true
+---
+
+# Forms & Validation for AgileSpace
+
+## Form Management
+
+### React Hook Form
+
+- Use react-hook-form for form state management
+- Leverage zod for schema validation
+- Use controlled inputs for better UX
+- Implement proper form submission handling
+
+```tsx
+// ✅ Good - Form with react-hook-form and zod
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { z } from "zod";
+
+const sessionSchema = z.object({
+  title: z
+    .string()
+    .min(1, "Title is required")
+    .max(100, "Title must be less than 100 characters"),
+  description: z.string().optional(),
+  track_id: z.string().optional(),
+  tags: z.array(z.string()).optional(),
+  estimated_duration: z
+    .number()
+    .min(1, "Duration must be at least 1 minute")
+    .optional(),
+});
+
+type SessionFormData = z.infer<typeof sessionSchema>;
+
+export function SessionForm({ onSubmit, defaultValues }: SessionFormProps) {
+  const form = useForm<SessionFormData>({
+    resolver: zodResolver(sessionSchema),
+    defaultValues: {
+      title: "",
+      description: "",
+      tags: [],
+      ...defaultValues,
+    },
+  });
+
+  const handleSubmit = form.handleSubmit((data) => {
+    onSubmit(data);
+  });
+
+  return (
+    <form onSubmit={handleSubmit} className="space-y-6">
+      <div className="space-y-2">
+        <Label htmlFor="title">Session Title *</Label>
+        <Input
+          id="title"
+          {...form.register("title")}
+          placeholder="Enter session title"
+          className={cn(form.formState.errors.title && "border-destructive")}
+        />
+        {form.formState.errors.title && (
+          <p className="text-sm text-destructive">
+            {form.formState.errors.title.message}
+          </p>
+        )}
+      </div>
+
+      <div className="space-y-2">
+        <Label htmlFor="description">Description</Label>
+        <Textarea
+          id="description"
+          {...form.register("description")}
+          placeholder="Enter session description"
+          className="min-h-[100px]"
+        />
+      </div>
+
+      <div className="flex items-center justify-end space-x-2">
+        <Button type="button" variant="outline" onClick={form.reset}>
+          Reset
+        </Button>
+        <Button type="submit" disabled={form.formState.isSubmitting}>
+          {form.formState.isSubmitting ? "Saving..." : "Save Session"}
+        </Button>
+      </div>
+    </form>
+  );
+}
+```
+
+### Form Components
+
+- Create reusable form components
+- Use consistent form patterns
+- Implement proper accessibility
+- Handle loading and error states
+
+```tsx
+// ✅ Good - Reusable form components
+interface FormFieldProps {
+  label: string;
+  name: string;
+  type?: "text" | "email" | "password" | "number" | "textarea";
+  placeholder?: string;
+  required?: boolean;
+  error?: string;
+  register: UseFormRegister<any>;
+}
+
+export function FormField({
+  label,
+  name,
+  type = "text",
+  placeholder,
+  required,
+  error,
+  register,
+}: FormFieldProps) {
+  const id = `field-${name}`;
+
+  return (
+    <div className="space-y-2">
+      <Label
+        htmlFor={id}
+        className={cn(
+          required && 'after:content-["*"] after:ml-0.5 after:text-destructive'
+        )}
+      >
+        {label}
+      </Label>
+
+      {type === "textarea" ? (
+        <Textarea
+          id={id}
+          {...register(name)}
+          placeholder={placeholder}
+          className={cn(error && "border-destructive")}
+        />
+      ) : (
+        <Input
+          id={id}
+          type={type}
+          {...register(name)}
+          placeholder={placeholder}
+          className={cn(error && "border-destructive")}
+        />
+      )}
+
+      {error && <p className="text-sm text-destructive">{error}</p>}
+    </div>
+  );
+}
+```
+
+## Validation Strategies
+
+### Client-Side Validation
+
+- Use zod schemas for type-safe validation
+- Provide immediate feedback to users
+- Validate on blur and submit
+- Show clear error messages
+
+```tsx
+// ✅ Good - Comprehensive validation schema
+const userProfileSchema = z.object({
+  name: z
+    .string()
+    .min(2, "Name must be at least 2 characters")
+    .max(50, "Name must be less than 50 characters")
+    .regex(/^[a-zA-Z\s]+$/, "Name can only contain letters and spaces"),
+
+  email: z
+    .string()
+    .email("Please enter a valid email address")
+    .min(1, "Email is required"),
+
+  avatar_url: z
+    .string()
+    .url("Please enter a valid URL")
+    .optional()
+    .or(z.literal("")),
+
+  timezone: z.string().min(1, "Timezone is required"),
+
+  working_hours: z
+    .object({
+      start: z
+        .string()
+        .regex(/^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$/, "Invalid time format"),
+      end: z
+        .string()
+        .regex(/^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$/, "Invalid time format"),
+    })
+    .refine(
+      (data) => {
+        const start = new Date(`2000-01-01T${data.start}`);
+        const end = new Date(`2000-01-01T${data.end}`);
+        return start < end;
+      },
+      {
+        message: "End time must be after start time",
+        path: ["end"],
+      }
+    ),
+});
+
+type UserProfileFormData = z.infer<typeof userProfileSchema>;
+```
+
+### Server-Side Validation
+
+- Always validate on the server
+- Use the same schemas for consistency
+- Handle validation errors gracefully
+- Provide meaningful error responses
+
+```tsx
+// ✅ Good - Server-side validation
+export async function updateUserProfile(
+  userId: string,
+  data: UserProfileFormData
+) {
+  try {
+    // Validate on server
+    const validatedData = userProfileSchema.parse(data);
+
+    const { error } = await supabase
+      .from("profiles")
+      .update(validatedData)
+      .eq("id", userId);
+
+    if (error) {
+      throw new Error(error.message);
+    }
+
+    return { success: true };
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return {
+        success: false,
+        errors: error.errors.map((err) => ({
+          field: err.path.join("."),
+          message: err.message,
+        })),
+      };
+    }
+
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : "An error occurred",
+    };
+  }
+}
+```
+
+## Form Patterns
+
+### Multi-Step Forms
+
+- Break complex forms into logical steps
+- Maintain form state across steps
+- Provide clear progress indicators
+- Allow navigation between steps
+
+```tsx
+// ✅ Good - Multi-step form
+export function MultiStepSessionForm() {
+  const [currentStep, setCurrentStep] = useState(1);
+  const totalSteps = 3;
+
+  const form = useForm<SessionFormData>({
+    resolver: zodResolver(sessionSchema),
+    defaultValues: {
+      title: "",
+      description: "",
+      track_id: "",
+      tags: [],
+    },
+  });
+
+  const nextStep = () => {
+    if (currentStep < totalSteps) {
+      setCurrentStep(currentStep + 1);
+    }
+  };
+
+  const prevStep = () => {
+    if (currentStep > 1) {
+      setCurrentStep(currentStep - 1);
+    }
+  };
+
+  return (
+    <div className="space-y-6">
+      {/* Progress indicator */}
+      <div className="flex items-center space-x-2">
+        {Array.from({ length: totalSteps }).map((_, i) => (
+          <div
+            key={i}
+            className={cn(
+              "h-2 flex-1 rounded-full",
+              i + 1 <= currentStep ? "bg-primary" : "bg-muted"
+            )}
+          />
+        ))}
+      </div>
+
+      {/* Form steps */}
+      {currentStep === 1 && (
+        <div className="space-y-4">
+          <h3 className="text-lg font-semibold">Basic Information</h3>
+          <FormField
+            label="Session Title"
+            name="title"
+            register={form.register}
+            error={form.formState.errors.title?.message}
+            required
+          />
+          <FormField
+            label="Description"
+            name="description"
+            type="textarea"
+            register={form.register}
+            error={form.formState.errors.description?.message}
+          />
+        </div>
+      )}
+
+      {currentStep === 2 && (
+        <div className="space-y-4">
+          <h3 className="text-lg font-semibold">Track & Tags</h3>
+          <TrackSelector
+            value={form.watch("track_id")}
+            onChange={(value) => form.setValue("track_id", value)}
+          />
+          <TagSelector
+            value={form.watch("tags")}
+            onChange={(value) => form.setValue("tags", value)}
+          />
+        </div>
+      )}
+
+      {currentStep === 3 && (
+        <div className="space-y-4">
+          <h3 className="text-lg font-semibold">Review & Submit</h3>
+          <SessionSummary data={form.getValues()} />
+        </div>
+      )}
+
+      {/* Navigation */}
+      <div className="flex items-center justify-between">
+        <Button
+          type="button"
+          variant="outline"
+          onClick={prevStep}
+          disabled={currentStep === 1}
+        >
+          Previous
+        </Button>
+
+        {currentStep < totalSteps ? (
+          <Button type="button" onClick={nextStep}>
+            Next
+          </Button>
+        ) : (
+          <Button
+            type="submit"
+            onClick={form.handleSubmit(onSubmit)}
+            disabled={form.formState.isSubmitting}
+          >
+            {form.formState.isSubmitting ? "Creating..." : "Create Session"}
+          </Button>
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+### Dynamic Forms
+
+- Handle conditional form fields
+- Use field arrays for repeatable sections
+- Implement dynamic validation
+- Manage complex form state
+
+```tsx
+// ✅ Good - Dynamic form with field arrays
+export function DynamicSessionForm() {
+  const form = useForm<SessionFormData>({
+    resolver: zodResolver(sessionSchema),
+  });
+
+  const { fields, append, remove } = useFieldArray({
+    control: form.control,
+    name: "tags",
+  });
+
+  return (
+    <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
+      {/* Basic fields */}
+      <FormField
+        label="Session Title"
+        name="title"
+        register={form.register}
+        error={form.formState.errors.title?.message}
+        required
+      />
+
+      {/* Dynamic tags */}
+      <div className="space-y-4">
+        <Label>Tags</Label>
+        {fields.map((field, index) => (
+          <div key={field.id} className="flex items-center space-x-2">
+            <Input
+              {...form.register(`tags.${index}`)}
+              placeholder="Enter tag name"
+            />
+            <Button
+              type="button"
+              variant="outline"
+              size="icon"
+              onClick={() => remove(index)}
+            >
+              <X className="h-4 w-4" />
+            </Button>
+          </div>
+        ))}
+        <Button type="button" variant="outline" onClick={() => append("")}>
+          Add Tag
+        </Button>
+      </div>
+
+      <Button type="submit" disabled={form.formState.isSubmitting}>
+        Save Session
+      </Button>
+    </form>
+  );
+}
+```
+
+## Error Handling
+
+### Form Error States
+
+- Display field-specific errors
+- Show form-level errors
+- Handle network errors gracefully
+- Provide retry mechanisms
+
+```tsx
+// ✅ Good - Comprehensive error handling
+export function SessionFormWithErrors() {
+  const [formError, setFormError] = useState<string | null>(null);
+
+  const form = useForm<SessionFormData>({
+    resolver: zodResolver(sessionSchema),
+  });
+
+  const onSubmit = async (data: SessionFormData) => {
+    try {
+      setFormError(null);
+      await createSession(data);
+      // Handle success
+    } catch (error) {
+      if (error instanceof z.ZodError) {
+        // Handle validation errors
+        error.errors.forEach((err) => {
+          form.setError(err.path.join(".") as any, {
+            type: "server",
+            message: err.message,
+          });
+        });
+      } else {
+        // Handle other errors
+        setFormError(
+          error instanceof Error ? error.message : "An error occurred"
+        );
+      }
+    }
+  };
+
+  return (
+    <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
+      {/* Form-level error */}
+      {formError && (
+        <Alert variant="destructive">
+          <AlertCircle className="h-4 w-4" />
+          <AlertDescription>{formError}</AlertDescription>
+        </Alert>
+      )}
+
+      {/* Form fields */}
+      <FormField
+        label="Session Title"
+        name="title"
+        register={form.register}
+        error={form.formState.errors.title?.message}
+        required
+      />
+
+      {/* Submit button */}
+      <Button
+        type="submit"
+        disabled={form.formState.isSubmitting}
+        className="w-full"
+      >
+        {form.formState.isSubmitting ? (
+          <>
+            <Loader2 className="mr-2 h-4 w-4 animate-spin" />
+            Creating Session...
+          </>
+        ) : (
+          "Create Session"
+        )}
+      </Button>
+    </form>
+  );
+}
+```
+
+### Validation Feedback
+
+- Provide immediate feedback
+- Use appropriate error styling
+- Show success states
+- Guide users to fix errors
+
+```tsx
+// ✅ Good - Validation feedback
+export function FormFieldWithFeedback({
+  label,
+  name,
+  register,
+  error,
+  touched,
+  ...props
+}: FormFieldProps) {
+  const [isTouched, setIsTouched] = useState(false);
+  const hasError = error && (touched || isTouched);
+
+  return (
+    <div className="space-y-2">
+      <Label htmlFor={name}>{label}</Label>
+
+      <div className="relative">
+        <Input
+          id={name}
+          {...register(name)}
+          onBlur={() => setIsTouched(true)}
+          className={cn(
+            hasError && "border-destructive focus-visible:ring-destructive",
+            !hasError &&
+              isTouched &&
+              "border-green-500 focus-visible:ring-green-500"
+          )}
+          {...props}
+        />
+
+        {/* Success indicator */}
+        {!hasError && isTouched && (
+          <Check className="absolute right-3 top-1/2 h-4 w-4 -translate-y-1/2 text-green-500" />
+        )}
+
+        {/* Error indicator */}
+        {hasError && (
+          <X className="absolute right-3 top-1/2 h-4 w-4 -translate-y-1/2 text-destructive" />
+        )}
+      </div>
+
+      {hasError && (
+        <p className="text-sm text-destructive flex items-center">
+          <AlertCircle className="mr-1 h-3 w-3" />
+          {error}
+        </p>
+      )}
+    </div>
+  );
+}
+```
diff --git a/.cursor/rules/General.mdc b/.cursor/rules/General.mdc
new file mode 100644
index 0000000..6bdfb20
--- /dev/null
+++ b/.cursor/rules/General.mdc
@@ -0,0 +1,677 @@
+---
+alwaysApply: true
+---
+
+# AgileSpace Project Rules
+
+## Project Overview
+
+AgileSpace is a modern web application that integrates with GitHub to provide comprehensive team effort tracking and visualization. It helps organizations monitor team performance, track issues, and generate insightful charts for better project management and resource allocation.
+
+## Task Management System
+
+### Task Structure
+
+- **Location**: All task files are in the `tasks/` folder (ignored by git)
+- **Status Indicators**:
+  - 🟢 COMPLETED - Feature fully implemented
+  - 🟡 PARTIALLY IMPLEMENTED - Feature partially done
+  - 🔴 NOT IMPLEMENTED - Feature not started
+  - 💡 SUGGESTED - Additional ideas and features
+
+### Task Organization
+
+```
+tasks/
+├── README.md                           # Task system overview
+├── TASKS.md                            # Main task breakdown
+├── HIERARCHICAL_TAGS_IMPLEMENTATION.md # Detailed implementation guide
+├── completed/                          # ✅ Completed features
+├── in-progress/                        # 🔄 Current work
+└── backlog/                           # ❌ Future tasks
+```
+
+### Task File Format
+
+Each task file should include:
+
+- **Status and priority**
+- **Overview and requirements**
+- **Required subtasks with checkboxes**
+- **Technical requirements**
+- **Files to create/modify**
+- **Success criteria**
+- **Notes and dependencies**
+
+## Current Project Status
+
+### ✅ Completed Features (3/13)
+
+1. **Active Users Tracking** - Real-time status updates
+2. **Current Task Display** - Shows what each user is working on
+3. **Task Time Tracking** - Real-time timer and duration tracking
+
+### 🔄 In Progress (1/13)
+
+4. **Hierarchical Tags System** - Enhanced issue type categorization
+
+### ❌ Backlog (9/13)
+
+5. **Daily Reporting** - Excel exports with time distribution
+6. **Effort Analysis** - Estimated vs actual time comparison
+7. **Team Overview** - Daily team productivity metrics
+8. **Weekly/Monthly Reports** - Extended reporting periods
+9. **Holiday Notifications** - Official holiday alerts
+10. **Attendance Tracking** - Login/logout monitoring
+11. **Time Off Requests** - Leave management system
+12. **Issue Creation** - Create GitHub issues from app
+13. **Additional Features** - Real-time notifications, analytics, etc.
+
+## Technology Stack
+
+### Frontend
+
+- **React 19** with TypeScript
+- **TanStack Router** for routing
+- **TanStack Query** for data fetching
+- **Tailwind CSS** for styling
+- **Radix UI** for components
+- **Recharts** for data visualization
+
+### Backend
+
+- **Supabase** for database and authentication
+- **PostgreSQL** for data storage
+- **GitHub API** integration via Octokit
+
+### Development Tools
+
+- **Vite** for build tooling
+- **pnpm** for package management
+- **ESLint** for code linting
+- **TypeScript** for type safety
+
+## Database Schema
+
+### Core Tables
+
+- `profiles` - User profiles with GitHub integration
+- `spaces` - Workspace/team spaces
+- `space_members` - Team membership with status tracking
+- `sessions` - Work sessions with time tracking
+- `tracks` - GitHub issues being tracked
+- `tags` - Hierarchical issue type categorization
+- `session_tags` - Many-to-many relationship for session tagging
+
+### Key Relationships
+
+- Sessions belong to tracks (GitHub issues)
+- Sessions belong to space members (users)
+- Sessions can have multiple tags (issue types)
+- Tags have hierarchical relationships (parent-child)
+
+## Code Organization
+
+### Source Structure
+
+```
+src/
+├── components/     # Reusable UI components
+├── hooks/         # Custom React hooks
+├── lib/           # Utility functions and shared logic
+│   ├── supabase/  # Supabase client and queries
+│   └── github/    # GitHub API integration
+├── routes/        # Page components (TanStack Router)
+├── types/         # TypeScript type definitions
+└── constants/     # Application constants
+```
+
+### Key Patterns
+
+- **Custom Hooks**: Use `use-*` prefix for React hooks
+- **API Hooks**: Use `use-*-api` prefix for data fetching hooks
+- **Components**: Use PascalCase and descriptive names
+- **Queries**: Separate queries and mutations in Supabase lib
+- **Types**: Export types from `src/types/index.ts`
+
+## Development Workflow
+
+### Task Implementation Process
+
+1. **Review Task File**: Check the detailed task file in `tasks/` folder
+2. **Understand Dependencies**: Ensure prerequisites are completed
+3. **Database Changes**: Create migrations if needed
+4. **Backend Updates**: Update queries/mutations
+5. **Frontend Components**: Create/update UI components
+6. **Integration**: Connect frontend to backend
+7. **Testing**: Verify functionality works as expected
+8. **Update Task Status**: Move task file to appropriate folder
+
+### Git Workflow
+
+- **Branch Naming**: `<type>/<ticket-number>-<description>`
+- **Commit Messages**: Follow Conventional Commits
+- **PR Format**: `<type>: <ticket-number> <description>`
+- **Task Files**: Never commit files in `tasks/` folder
+
+### Database Migrations
+
+- **Location**: `supabase/migrations/`
+- **Naming**: `YYYYMMDDHHMMSS_description.sql`
+- **Commands**:
+  - `pnpm supabase migration new <name>`
+  - `pnpm supabase db reset`
+  - `pnpm supabase db push`
+
+## Current Focus Areas
+
+### Immediate Priority (Task 4 - Hierarchical Tags)
+
+- Add hierarchy fields to tags table
+- Create predefined issue type structure
+- Build hierarchical tag selector component
+- Integrate with session creation workflow
+- Update reporting for issue type aggregation
+
+### Key Implementation Details
+
+- **Hierarchical Structure**: Parent-child relationships for tags
+- **Issue Types**: Meeting, Development, Project Management categories
+- **Backward Compatibility**: Existing tags must continue working
+- **Performance**: Efficient queries for large datasets
+- **User Experience**: Intuitive two-level selection
+
+## Code Standards
+
+### TypeScript
+
+- Use strict type checking
+- Define interfaces for all data structures
+- Use generic types where appropriate
+- Avoid `any` type usage
+
+### React
+
+- Use functional components with hooks
+- Implement proper error boundaries
+- Use React Query for data fetching
+- Follow React best practices
+
+### Database
+
+- Use proper foreign key constraints
+- Implement data validation
+- Use indexes for performance
+- Follow PostgreSQL best practices
+
+### Styling
+
+- Use Tailwind CSS utility classes
+- Follow design system patterns
+- Ensure responsive design
+- Maintain accessibility standards
+
+## Testing Strategy
+
+### Unit Tests
+
+- Test individual functions and components
+- Mock external dependencies
+- Use descriptive test names
+- Maintain good test coverage
+
+### Integration Tests
+
+- Test API endpoints
+- Verify database operations
+- Test component interactions
+- Validate data flow
+
+### User Acceptance Tests
+
+- Test complete user workflows
+- Verify feature requirements
+- Test edge cases and error handling
+- Validate user experience
+
+## Performance Considerations
+
+### Frontend
+
+- Use React Query for caching
+- Implement proper loading states
+- Optimize bundle size
+- Use lazy loading where appropriate
+
+### Backend
+
+- Optimize database queries
+- Use proper indexing
+- Implement pagination
+- Cache frequently accessed data
+
+### Monitoring
+
+- Track query performance
+- Monitor user interactions
+- Log errors and exceptions
+- Measure response times
+
+## Security Guidelines
+
+### Authentication
+
+- Use Supabase Auth
+- Implement proper role-based access
+- Validate user permissions
+- Secure API endpoints
+
+### Data Protection
+
+- Validate all inputs
+- Use parameterized queries
+- Implement rate limiting
+- Protect sensitive information
+
+### GitHub Integration
+
+- Use proper OAuth scopes
+- Validate webhook signatures
+- Secure API tokens
+- Handle rate limits
+
+## Deployment
+
+### Environment Setup
+
+- Configure environment variables
+- Set up Supabase project
+- Configure GitHub OAuth
+- Set up monitoring
+
+### Build Process
+
+- Run type checking
+- Execute linting
+- Build production assets
+- Run tests
+
+### Release Process
+
+- Create release branch
+- Update version numbers
+- Generate changelog
+- Deploy to production
+
+## Support and Maintenance
+
+### Documentation
+
+- Keep README updated
+- Document API changes
+- Maintain task documentation
+- Update implementation guides
+
+### Monitoring
+
+- Track application health
+- Monitor error rates
+- Watch performance metrics
+- Alert on issues
+
+### Updates
+
+- Keep dependencies updated
+- Apply security patches
+- Monitor for breaking changes
+- Test thoroughly before updates
+
+## AI Assistance Guidelines
+
+When working with AI assistance:
+
+1. **Reference Task Files**: Always check the relevant task file in `tasks/` folder
+2. **Follow Patterns**: Use existing code patterns and conventions
+3. **Consider Dependencies**: Ensure prerequisites are met before implementation
+4. **Update Documentation**: Keep task files and documentation current
+5. **Test Thoroughly**: Verify implementations work as expected
+6. **Maintain Consistency**: Follow established naming and structure patterns
+
+Remember: The `tasks/` folder contains the source of truth for project requirements and implementation details. Always refer to these files when implementing features or making architectural decisions.
+
+# AgileSpace Project Rules
+
+## Project Overview
+
+AgileSpace is a modern web application that integrates with GitHub to provide comprehensive team effort tracking and visualization. It helps organizations monitor team performance, track issues, and generate insightful charts for better project management and resource allocation.
+
+## Task Management System
+
+### Task Structure
+
+- **Location**: All task files are in the `tasks/` folder (ignored by git)
+- **Status Indicators**:
+  - 🟢 COMPLETED - Feature fully implemented
+  - 🟡 PARTIALLY IMPLEMENTED - Feature partially done
+  - 🔴 NOT IMPLEMENTED - Feature not started
+  - 💡 SUGGESTED - Additional ideas and features
+
+### Task Organization
+
+```
+tasks/
+├── README.md                           # Task system overview
+├── TASKS.md                            # Main task breakdown
+├── HIERARCHICAL_TAGS_IMPLEMENTATION.md # Detailed implementation guide
+├── completed/                          # ✅ Completed features
+├── in-progress/                        # 🔄 Current work
+└── backlog/                           # ❌ Future tasks
+```
+
+### Task File Format
+
+Each task file should include:
+
+- **Status and priority**
+- **Overview and requirements**
+- **Required subtasks with checkboxes**
+- **Technical requirements**
+- **Files to create/modify**
+- **Success criteria**
+- **Notes and dependencies**
+
+## Current Project Status
+
+### ✅ Completed Features (3/13)
+
+1. **Active Users Tracking** - Real-time status updates
+2. **Current Task Display** - Shows what each user is working on
+3. **Task Time Tracking** - Real-time timer and duration tracking
+
+### 🔄 In Progress (1/13)
+
+4. **Hierarchical Tags System** - Enhanced issue type categorization
+
+### ❌ Backlog (9/13)
+
+5. **Daily Reporting** - Excel exports with time distribution
+6. **Effort Analysis** - Estimated vs actual time comparison
+7. **Team Overview** - Daily team productivity metrics
+8. **Weekly/Monthly Reports** - Extended reporting periods
+9. **Holiday Notifications** - Official holiday alerts
+10. **Attendance Tracking** - Login/logout monitoring
+11. **Time Off Requests** - Leave management system
+12. **Issue Creation** - Create GitHub issues from app
+13. **Additional Features** - Real-time notifications, analytics, etc.
+
+## Technology Stack
+
+### Frontend
+
+- **React 19** with TypeScript
+- **TanStack Router** for routing
+- **TanStack Query** for data fetching
+- **Tailwind CSS** for styling
+- **Radix UI** for components
+- **Recharts** for data visualization
+
+### Backend
+
+- **Supabase** for database and authentication
+- **PostgreSQL** for data storage
+- **GitHub API** integration via Octokit
+
+### Development Tools
+
+- **Vite** for build tooling
+- **pnpm** for package management
+- **ESLint** for code linting
+- **TypeScript** for type safety
+
+## Database Schema
+
+### Core Tables
+
+- `profiles` - User profiles with GitHub integration
+- `spaces` - Workspace/team spaces
+- `space_members` - Team membership with status tracking
+- `sessions` - Work sessions with time tracking
+- `tracks` - GitHub issues being tracked
+- `tags` - Hierarchical issue type categorization
+- `session_tags` - Many-to-many relationship for session tagging
+
+### Key Relationships
+
+- Sessions belong to tracks (GitHub issues)
+- Sessions belong to space members (users)
+- Sessions can have multiple tags (issue types)
+- Tags have hierarchical relationships (parent-child)
+
+## Code Organization
+
+### Source Structure
+
+```
+src/
+├── components/     # Reusable UI components
+├── hooks/         # Custom React hooks
+├── lib/           # Utility functions and shared logic
+│   ├── supabase/  # Supabase client and queries
+│   └── github/    # GitHub API integration
+├── routes/        # Page components (TanStack Router)
+├── types/         # TypeScript type definitions
+└── constants/     # Application constants
+```
+
+### Key Patterns
+
+- **Custom Hooks**: Use `use-*` prefix for React hooks
+- **API Hooks**: Use `use-*-api` prefix for data fetching hooks
+- **Components**: Use PascalCase and descriptive names
+- **Queries**: Separate queries and mutations in Supabase lib
+- **Types**: Export types from `src/types/index.ts`
+
+## Development Workflow
+
+### Task Implementation Process
+
+1. **Review Task File**: Check the detailed task file in `tasks/` folder
+2. **Understand Dependencies**: Ensure prerequisites are completed
+3. **Database Changes**: Create migrations if needed
+4. **Backend Updates**: Update queries/mutations
+5. **Frontend Components**: Create/update UI components
+6. **Integration**: Connect frontend to backend
+7. **Testing**: Verify functionality works as expected
+8. **Update Task Status**: Move task file to appropriate folder
+
+### Git Workflow
+
+- **Branch Naming**: `<type>/<ticket-number>-<description>`
+- **Commit Messages**: Follow Conventional Commits
+- **PR Format**: `<type>: <ticket-number> <description>`
+- **Task Files**: Never commit files in `tasks/` folder
+
+### Database Migrations
+
+- **Location**: `supabase/migrations/`
+- **Naming**: `YYYYMMDDHHMMSS_description.sql`
+- **Commands**:
+  - `pnpm supabase migration new <name>`
+  - `pnpm supabase db reset`
+  - `pnpm supabase db push`
+
+## Current Focus Areas
+
+### Immediate Priority (Task 4 - Hierarchical Tags)
+
+- Add hierarchy fields to tags table
+- Create predefined issue type structure
+- Build hierarchical tag selector component
+- Integrate with session creation workflow
+- Update reporting for issue type aggregation
+
+### Key Implementation Details
+
+- **Hierarchical Structure**: Parent-child relationships for tags
+- **Issue Types**: Meeting, Development, Project Management categories
+- **Backward Compatibility**: Existing tags must continue working
+- **Performance**: Efficient queries for large datasets
+- **User Experience**: Intuitive two-level selection
+
+## Code Standards
+
+### TypeScript
+
+- Use strict type checking
+- Define interfaces for all data structures
+- Use generic types where appropriate
+- Avoid `any` type usage
+
+### React
+
+- Use functional components with hooks
+- Implement proper error boundaries
+- Use React Query for data fetching
+- Follow React best practices
+
+### Database
+
+- Use proper foreign key constraints
+- Implement data validation
+- Use indexes for performance
+- Follow PostgreSQL best practices
+
+### Styling
+
+- Use Tailwind CSS utility classes
+- Follow design system patterns
+- Ensure responsive design
+- Maintain accessibility standards
+
+## Testing Strategy
+
+### Unit Tests
+
+- Test individual functions and components
+- Mock external dependencies
+- Use descriptive test names
+- Maintain good test coverage
+
+### Integration Tests
+
+- Test API endpoints
+- Verify database operations
+- Test component interactions
+- Validate data flow
+
+### User Acceptance Tests
+
+- Test complete user workflows
+- Verify feature requirements
+- Test edge cases and error handling
+- Validate user experience
+
+## Performance Considerations
+
+### Frontend
+
+- Use React Query for caching
+- Implement proper loading states
+- Optimize bundle size
+- Use lazy loading where appropriate
+
+### Backend
+
+- Optimize database queries
+- Use proper indexing
+- Implement pagination
+- Cache frequently accessed data
+
+### Monitoring
+
+- Track query performance
+- Monitor user interactions
+- Log errors and exceptions
+- Measure response times
+
+## Security Guidelines
+
+### Authentication
+
+- Use Supabase Auth
+- Implement proper role-based access
+- Validate user permissions
+- Secure API endpoints
+
+### Data Protection
+
+- Validate all inputs
+- Use parameterized queries
+- Implement rate limiting
+- Protect sensitive information
+
+### GitHub Integration
+
+- Use proper OAuth scopes
+- Validate webhook signatures
+- Secure API tokens
+- Handle rate limits
+
+## Deployment
+
+### Environment Setup
+
+- Configure environment variables
+- Set up Supabase project
+- Configure GitHub OAuth
+- Set up monitoring
+
+### Build Process
+
+- Run type checking
+- Execute linting
+- Build production assets
+- Run tests
+
+### Release Process
+
+- Create release branch
+- Update version numbers
+- Generate changelog
+- Deploy to production
+
+## Support and Maintenance
+
+### Documentation
+
+- Keep README updated
+- Document API changes
+- Maintain task documentation
+- Update implementation guides
+
+### Monitoring
+
+- Track application health
+- Monitor error rates
+- Watch performance metrics
+- Alert on issues
+
+### Updates
+
+- Keep dependencies updated
+- Apply security patches
+- Monitor for breaking changes
+- Test thoroughly before updates
+
+## AI Assistance Guidelines
+
+When working with AI assistance:
+
+1. **Reference Task Files**: Always check the relevant task file in `tasks/` folder
+2. **Follow Patterns**: Use existing code patterns and conventions
+3. **Consider Dependencies**: Ensure prerequisites are met before implementation
+4. **Update Documentation**: Keep task files and documentation current
+5. **Test Thoroughly**: Verify implementations work as expected
+6. **Maintain Consistency**: Follow established naming and structure patterns
+
+Remember: The `tasks/` folder contains the source of truth for project requirements and implementation details. Always refer to these files when implementing features or making architectural decisions.
diff --git a/.cursor/rules/Naming-Conventions.mdc b/.cursor/rules/Naming-Conventions.mdc
new file mode 100644
index 0000000..6e5669f
--- /dev/null
+++ b/.cursor/rules/Naming-Conventions.mdc
@@ -0,0 +1,553 @@
+---
+alwaysApply: true
+---
+
+# Naming Conventions for AgileSpace
+
+## File and Directory Naming
+
+### File Extensions
+
+- **Components**: Use `.tsx` extension
+- **Hooks/Utils**: Use `.ts` extension
+- **Type definitions**: Use `.ts` extension
+- **Test files**: Use `.test.ts` or `.test.tsx` extension
+
+### Directory Structure
+
+- Use kebab-case for directory names
+- Group related files in descriptive directories
+- Use lowercase with dashes (e.g., `components/auth-wizard`)
+
+```tsx
+// ✅ Good - File organization
+src/
+├── components/
+│   ├── session-card.tsx
+│   ├── session-timer.tsx
+│   ├── session-list.tsx
+│   └── ui/
+│       ├── button.tsx
+│       ├── card.tsx
+│       └── dialog.tsx
+├── hooks/
+│   ├── use-sessions.ts
+│   ├── use-sessions-api.ts
+│   └── use-session-timer.ts
+├── lib/
+│   ├── supabase/
+│   │   ├── client.ts
+│   │   ├── queries.ts
+│   │   └── mutations.ts
+│   └── utils.ts
+└── types/
+    ├── index.ts
+    └── database.types.ts
+```
+
+## Component Naming
+
+### Component Files
+
+- Use PascalCase for component file names
+- Match the component name to the file name
+- Use descriptive, purpose-indicating names
+
+```tsx
+// ✅ Good - Component file naming
+// session-card.tsx
+export function SessionCard({ session }: SessionCardProps) {
+  // Component implementation
+}
+
+// session-timer.tsx
+export function SessionTimer({ sessionId }: SessionTimerProps) {
+  // Component implementation
+}
+
+// space-sidebar.tsx
+export function SpaceSidebar({ space }: SpaceSidebarProps) {
+  // Component implementation
+}
+```
+
+### Component Exports
+
+- Prefer named exports for components
+- Use default exports sparingly
+- Export types and interfaces from the same file
+
+```tsx
+// ✅ Good - Named exports
+export function SessionCard({ session }: SessionCardProps) {
+  // Component implementation
+}
+
+export interface SessionCardProps {
+  session: Session;
+  onEndSession?: (sessionId: string) => void;
+  onEditSession?: (session: Session) => void;
+}
+
+// ✅ Good - Multiple exports from same file
+export function SessionList({ sessions }: SessionListProps) {
+  // Component implementation
+}
+
+export function SessionListSkeleton() {
+  // Skeleton component
+}
+
+export interface SessionListProps {
+  sessions: Session[];
+}
+```
+
+## Hook Naming
+
+### Custom Hooks
+
+- Use `use-*` prefix for custom hooks
+- Use `use-*-api` prefix for data fetching hooks
+- Use descriptive names that indicate purpose
+
+```tsx
+// ✅ Good - Hook naming
+// use-sessions.ts
+export function useSessions(spaceId: string) {
+  // Hook implementation
+}
+
+// use-sessions-api.ts
+export function useSessionsApi(spaceId: string) {
+  // API hook implementation
+}
+
+// use-session-timer.ts
+export function useSessionTimer(sessionId: string) {
+  // Timer hook implementation
+}
+
+// use-debounce.ts
+export function useDebounce<T>(value: T, delay: number): T {
+  // Debounce hook implementation
+}
+```
+
+### Hook File Organization
+
+- One hook per file for complex hooks
+- Group related hooks in the same file
+- Export types and utilities from hook files
+
+```tsx
+// ✅ Good - Hook file organization
+// hooks/use-sessions.ts
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { supabase } from "@/lib/supabase/client";
+
+export function useSessionsApi(spaceId: string) {
+  return useQuery({
+    queryKey: ["sessions", spaceId],
+    queryFn: () => getSessions(spaceId),
+  });
+}
+
+export function useCreateSessionApi() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: createSession,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["sessions"] });
+    },
+  });
+}
+
+// Helper functions
+async function getSessions(spaceId: string): Promise<Session[]> {
+  const { data, error } = await supabase
+    .from("sessions")
+    .select("*")
+    .eq("space_id", spaceId);
+
+  if (error) throw error;
+  return data;
+}
+```
+
+## Variable and Function Naming
+
+### Variables
+
+- Use camelCase for variables
+- Use descriptive names with auxiliary verbs
+- Prefix boolean variables with is/has/can/should
+
+```tsx
+// ✅ Good - Variable naming
+const isLoading = query.isLoading;
+const hasError = query.error !== null;
+const canEdit = user.permissions.includes("edit");
+const shouldShowTimer = session.status === "active";
+const sessionDuration = calculateDuration(session.start_time, session.end_time);
+const activeSessions = sessions.filter((session) => !session.end_time);
+const totalTimeSpent = sessions.reduce(
+  (total, session) => total + session.duration,
+  0
+);
+
+// ❌ Avoid - Poor variable naming
+const loading = query.isLoading;
+const error = query.error !== null;
+const edit = user.permissions.includes("edit");
+const timer = session.status === "active";
+const duration = calculateDuration(session.start_time, session.end_time);
+const filtered = sessions.filter((session) => !session.end_time);
+const total = sessions.reduce((total, session) => total + session.duration, 0);
+```
+
+### Functions
+
+- Use camelCase for functions
+- Use descriptive names that indicate action
+- Use verb-noun combinations for clarity
+
+```tsx
+// ✅ Good - Function naming
+function calculateSessionDuration(startTime: string, endTime?: string): number {
+  // Function implementation
+}
+
+function formatDuration(minutes: number): string {
+  // Function implementation
+}
+
+function validateSessionData(data: SessionFormData): ValidationResult {
+  // Function implementation
+}
+
+function handleSessionEnd(sessionId: string): void {
+  // Function implementation
+}
+
+function createNewSession(sessionData: SessionInsert): Promise<Session> {
+  // Function implementation
+}
+
+// ❌ Avoid - Poor function naming
+function calc(startTime: string, endTime?: string): number {
+  // Function implementation
+}
+
+function format(minutes: number): string {
+  // Function implementation
+}
+
+function validate(data: SessionFormData): ValidationResult {
+  // Function implementation
+}
+
+function end(sessionId: string): void {
+  // Function implementation
+}
+
+function create(data: SessionInsert): Promise<Session> {
+  // Function implementation
+}
+```
+
+## Type and Interface Naming
+
+### Type Definitions
+
+- Use PascalCase for types and interfaces
+- Use descriptive names that indicate purpose
+- Use appropriate suffixes (Props, State, Config, etc.)
+
+```tsx
+// ✅ Good - Type naming
+interface SessionCardProps {
+  session: Session;
+  onEndSession?: (sessionId: string) => void;
+  onEditSession?: (session: Session) => void;
+}
+
+interface SessionFormData {
+  title: string;
+  description?: string;
+  track_id?: string;
+  tags: string[];
+}
+
+type SessionStatus = "active" | "completed" | "paused";
+type SessionDuration = number; // in minutes
+type ValidationResult = { isValid: boolean; errors: string[] };
+
+interface ApiResponse<T> {
+  data: T | null;
+  error: string | null;
+}
+
+// ❌ Avoid - Poor type naming
+interface Props {
+  session: Session;
+  onEnd?: (sessionId: string) => void;
+  onEdit?: (session: Session) => void;
+}
+
+interface FormData {
+  title: string;
+  description?: string;
+  track_id?: string;
+  tags: string[];
+}
+
+type Status = "active" | "completed" | "paused";
+type Duration = number;
+type Result = { isValid: boolean; errors: string[] };
+```
+
+### Database Types
+
+- Use database table names as base for types
+- Add appropriate suffixes for different operations
+- Maintain consistency with Supabase generated types
+
+```tsx
+// ✅ Good - Database type naming
+import type { Database } from "@/types/database.types";
+
+// Base types from database
+type Session = Database["public"]["Tables"]["sessions"]["Row"];
+type SessionInsert = Database["public"]["Tables"]["sessions"]["Insert"];
+type SessionUpdate = Database["public"]["Tables"]["sessions"]["Update"];
+
+// Extended types for specific use cases
+interface SessionWithRelations extends Session {
+  member: Profile;
+  tags: Tag[];
+  track?: Track;
+}
+
+interface SessionWithStats extends Session {
+  duration: number;
+  isActive: boolean;
+  formattedDuration: string;
+}
+
+// Form types
+interface SessionFormData {
+  title: string;
+  description?: string;
+  track_id?: string;
+  tags: string[];
+}
+```
+
+## Constant Naming
+
+### Constants
+
+- Use UPPER_SNAKE_CASE for constants
+- Use descriptive names that indicate purpose
+- Group related constants together
+
+```tsx
+// ✅ Good - Constant naming
+// API endpoints
+export const API_ENDPOINTS = {
+  SESSIONS: "/api/sessions",
+  SPACES: "/api/spaces",
+  MEMBERS: "/api/members",
+} as const;
+
+// Session statuses
+export const SESSION_STATUSES = {
+  ACTIVE: "active",
+  COMPLETED: "completed",
+  PAUSED: "paused",
+} as const;
+
+// Time constants
+export const TIMER_UPDATE_INTERVAL = 1000; // milliseconds
+export const SESSION_TIMEOUT = 30 * 60 * 1000; // 30 minutes
+export const CACHE_STALE_TIME = 5 * 60 * 1000; // 5 minutes
+
+// UI constants
+export const MAX_TITLE_LENGTH = 100;
+export const MAX_DESCRIPTION_LENGTH = 500;
+export const MIN_SESSION_DURATION = 1; // minutes
+
+// ❌ Avoid - Poor constant naming
+export const endpoints = {
+  sessions: "/api/sessions",
+  spaces: "/api/spaces",
+  members: "/api/members",
+};
+
+export const statuses = {
+  active: "active",
+  completed: "completed",
+  paused: "paused",
+};
+
+export const interval = 1000;
+export const timeout = 30 * 60 * 1000;
+export const staleTime = 5 * 60 * 1000;
+```
+
+## Event Handler Naming
+
+### Event Handlers
+
+- Use `handle*` prefix for event handlers
+- Use descriptive names that indicate the action
+- Be specific about what is being handled
+
+```tsx
+// ✅ Good - Event handler naming
+function handleSessionEnd(sessionId: string): void {
+  // Handle session end
+}
+
+function handleSessionEdit(session: Session): void {
+  // Handle session edit
+}
+
+function handleFormSubmit(event: React.FormEvent): void {
+  // Handle form submission
+}
+
+function handleInputChange(event: React.ChangeEvent<HTMLInputElement>): void {
+  // Handle input change
+}
+
+function handleKeyDown(event: React.KeyboardEvent): void {
+  // Handle key down
+}
+
+function handleClick(event: React.MouseEvent): void {
+  // Handle click
+}
+
+// ❌ Avoid - Poor event handler naming
+function end(sessionId: string): void {
+  // Handle session end
+}
+
+function edit(session: Session): void {
+  // Handle session edit
+}
+
+function submit(event: React.FormEvent): void {
+  // Handle form submission
+}
+
+function change(event: React.ChangeEvent<HTMLInputElement>): void {
+  // Handle input change
+}
+
+function keyDown(event: React.KeyboardEvent): void {
+  // Handle key down
+}
+
+function click(event: React.MouseEvent): void {
+  // Handle click
+}
+```
+
+## CSS Class Naming
+
+### Tailwind CSS Classes
+
+- Use Tailwind's utility classes
+- Use the `cn` utility for conditional classes
+- Group related classes together
+- Use semantic class names when possible
+
+```tsx
+// ✅ Good - CSS class organization
+import { cn } from "@/lib/utils";
+
+export function Button({
+  variant = "default",
+  size = "default",
+  className,
+  ...props
+}: ButtonProps) {
+  return (
+    <button
+      className={cn(
+        // Base styles
+        "inline-flex items-center justify-center rounded-md text-sm font-medium",
+        "transition-colors focus-visible:outline-none focus-visible:ring-2",
+        "focus-visible:ring-ring focus-visible:ring-offset-2",
+        "disabled:pointer-events-none disabled:opacity-50",
+
+        // Variant styles
+        variant === "default" &&
+          "bg-primary text-primary-foreground hover:bg-primary/90",
+        variant === "destructive" &&
+          "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+        variant === "outline" &&
+          "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        variant === "secondary" &&
+          "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        variant === "ghost" && "hover:bg-accent hover:text-accent-foreground",
+        variant === "link" && "text-primary underline-offset-4 hover:underline",
+
+        // Size styles
+        size === "default" && "h-10 px-4 py-2",
+        size === "sm" && "h-9 rounded-md px-3",
+        size === "lg" && "h-11 rounded-md px-8",
+        size === "icon" && "h-10 w-10",
+
+        // Custom classes
+        className
+      )}
+      {...props}
+    />
+  );
+}
+```
+
+## Import Organization
+
+### Import Statements
+
+- Group imports by type and source
+- Use absolute imports for project files
+- Use relative imports for closely related files
+- Order imports consistently
+
+```tsx
+// ✅ Good - Import organization
+// 1. React and external libraries
+import { useState, useEffect, useCallback } from "react";
+import { useQuery, useMutation } from "@tanstack/react-query";
+
+// 2. UI components
+import { Button } from "@/components/ui/button";
+import { Card, CardHeader, CardTitle } from "@/components/ui/card";
+
+// 3. Custom hooks
+import { useSessionsApi } from "@/hooks/api/use-sessions";
+
+// 4. Utilities and types
+import { cn, formatDate } from "@/lib/utils";
+import type { Session } from "@/types";
+
+// 5. Relative imports (if any)
+import { SessionTimer } from "./session-timer";
+
+// ❌ Avoid - Poor import organization
+import { SessionTimer } from "./session-timer";
+import { useSessionsApi } from "@/hooks/api/use-sessions";
+import { useState, useEffect, useCallback } from "react";
+import { Button } from "@/components/ui/button";
+import { cn, formatDate } from "@/lib/utils";
+import { useQuery, useMutation } from "@tanstack/react-query";
+import type { Session } from "@/types";
+import { Card, CardHeader, CardTitle } from "@/components/ui/card";
+```
diff --git a/.cursor/rules/Performance-Optimization.mdc b/.cursor/rules/Performance-Optimization.mdc
new file mode 100644
index 0000000..c6ccae0
--- /dev/null
+++ b/.cursor/rules/Performance-Optimization.mdc
@@ -0,0 +1,550 @@
+---
+alwaysApply: true
+---
+
+# Performance Optimization for AgileSpace
+
+## React Performance
+
+### Component Optimization
+
+- Use React.memo for expensive components
+- Implement useCallback for event handlers
+- Use useMemo for expensive calculations
+- Avoid unnecessary re-renders
+
+```tsx
+// ✅ Good - Optimized component
+export const SessionCard = React.memo(function SessionCard({
+  session,
+  onEndSession,
+  onEditSession,
+}: SessionCardProps) {
+  const handleEndSession = useCallback(() => {
+    onEndSession(session.id);
+  }, [session.id, onEndSession]);
+
+  const handleEditSession = useCallback(() => {
+    onEditSession(session);
+  }, [session, onEditSession]);
+
+  const formattedDuration = useMemo(() => {
+    return formatDuration(session.start_time, session.end_time);
+  }, [session.start_time, session.end_time]);
+
+  return (
+    <Card className="hover:shadow-md transition-shadow">
+      <CardHeader>
+        <CardTitle className="text-lg">{session.title}</CardTitle>
+        <p className="text-sm text-muted-foreground">{session.description}</p>
+      </CardHeader>
+      <CardContent>
+        <div className="flex items-center justify-between">
+          <span className="text-sm text-muted-foreground">
+            {formattedDuration}
+          </span>
+          <div className="flex space-x-2">
+            <Button size="sm" variant="outline" onClick={handleEditSession}>
+              Edit
+            </Button>
+            <Button size="sm" variant="destructive" onClick={handleEndSession}>
+              End
+            </Button>
+          </div>
+        </div>
+      </CardContent>
+    </Card>
+  );
+});
+```
+
+### List Optimization
+
+- Use virtualization for large lists
+- Implement proper key props
+- Avoid inline functions in map
+- Use windowing techniques
+
+```tsx
+// ✅ Good - Optimized list rendering
+import { FixedSizeList as List } from "react-window";
+
+export function SessionList({ sessions }: SessionListProps) {
+  const Row = useCallback(
+    ({ index, style }: { index: number; style: CSSProperties }) => {
+      const session = sessions[index];
+      return (
+        <div style={style}>
+          <SessionCard
+            session={session}
+            onEndSession={handleEndSession}
+            onEditSession={handleEditSession}
+          />
+        </div>
+      );
+    },
+    [sessions, handleEndSession, handleEditSession]
+  );
+
+  return (
+    <List height={600} itemCount={sessions.length} itemSize={120} width="100%">
+      {Row}
+    </List>
+  );
+}
+
+// ✅ Good - Simple list with proper keys
+export function SimpleSessionList({ sessions }: SessionListProps) {
+  return (
+    <div className="space-y-4">
+      {sessions.map((session) => (
+        <SessionCard
+          key={session.id} // Use stable, unique keys
+          session={session}
+          onEndSession={handleEndSession}
+          onEditSession={handleEditSession}
+        />
+      ))}
+    </div>
+  );
+}
+```
+
+## Data Fetching Optimization
+
+### TanStack Query Optimization
+
+- Use appropriate stale times
+- Implement proper cache invalidation
+- Use optimistic updates
+- Leverage background refetching
+
+```tsx
+// ✅ Good - Optimized data fetching
+export function useSessionsApi(spaceId: string) {
+  return useQuery({
+    queryKey: ["sessions", spaceId],
+    queryFn: () => getSessions(spaceId),
+    staleTime: 5 * 60 * 1000, // 5 minutes
+    gcTime: 10 * 60 * 1000, // 10 minutes
+    refetchOnWindowFocus: false,
+    refetchOnReconnect: true,
+  });
+}
+
+// ✅ Good - Optimistic updates
+export function useCreateSessionApi() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: createSession,
+    onMutate: async (newSession) => {
+      // Cancel outgoing refetches
+      await queryClient.cancelQueries({ queryKey: ["sessions"] });
+
+      // Snapshot previous value
+      const previousSessions = queryClient.getQueryData([
+        "sessions",
+        newSession.space_id,
+      ]);
+
+      // Optimistically update
+      queryClient.setQueryData(
+        ["sessions", newSession.space_id],
+        (old: Session[] = []) => [
+          ...old,
+          {
+            ...newSession,
+            id: "temp-id",
+            created_at: new Date().toISOString(),
+          },
+        ]
+      );
+
+      return { previousSessions };
+    },
+    onError: (err, newSession, context) => {
+      // Revert on error
+      queryClient.setQueryData(
+        ["sessions", newSession.space_id],
+        context?.previousSessions
+      );
+    },
+    onSettled: () => {
+      // Always refetch after error or success
+      queryClient.invalidateQueries({ queryKey: ["sessions"] });
+    },
+  });
+}
+```
+
+### Pagination and Infinite Loading
+
+- Implement proper pagination
+- Use infinite queries for large datasets
+- Cache paginated data efficiently
+- Handle loading states properly
+
+```tsx
+// ✅ Good - Infinite loading
+export function useInfiniteSessionsApi(spaceId: string) {
+  return useInfiniteQuery({
+    queryKey: ["sessions", "infinite", spaceId],
+    queryFn: ({ pageParam = 0 }) => getSessionsPaginated(spaceId, pageParam),
+    getNextPageParam: (lastPage, pages) => {
+      return lastPage.hasMore ? pages.length : undefined;
+    },
+    staleTime: 5 * 60 * 1000,
+    gcTime: 10 * 60 * 1000,
+  });
+}
+
+// ✅ Good - Paginated list component
+export function InfiniteSessionList({ spaceId }: { spaceId: string }) {
+  const { data, fetchNextPage, hasNextPage, isFetchingNextPage, isLoading } =
+    useInfiniteSessionsApi(spaceId);
+
+  const allSessions = useMemo(() => {
+    return data?.pages.flatMap((page) => page.sessions) ?? [];
+  }, [data]);
+
+  if (isLoading) {
+    return <SessionListSkeleton />;
+  }
+
+  return (
+    <div className="space-y-4">
+      {allSessions.map((session) => (
+        <SessionCard key={session.id} session={session} />
+      ))}
+
+      {hasNextPage && (
+        <div className="flex justify-center">
+          <Button
+            onClick={() => fetchNextPage()}
+            disabled={isFetchingNextPage}
+            variant="outline"
+          >
+            {isFetchingNextPage ? "Loading..." : "Load More"}
+          </Button>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+## Bundle Optimization
+
+### Code Splitting
+
+- Use React.lazy for route-based splitting
+- Implement dynamic imports for heavy components
+- Split vendor bundles appropriately
+- Use webpack bundle analyzer
+
+```tsx
+// ✅ Good - Route-based code splitting
+import { lazy, Suspense } from "react";
+
+const SessionChart = lazy(() => import("./session-chart"));
+const SessionReport = lazy(() => import("./session-report"));
+const Analytics = lazy(() => import("./analytics"));
+
+export function Dashboard() {
+  return (
+    <div className="space-y-6">
+      <Suspense fallback={<div>Loading chart...</div>}>
+        <SessionChart />
+      </Suspense>
+
+      <Suspense fallback={<div>Loading report...</div>}>
+        <SessionReport />
+      </Suspense>
+
+      <Suspense fallback={<div>Loading analytics...</div>}>
+        <Analytics />
+      </Suspense>
+    </div>
+  );
+}
+
+// ✅ Good - Dynamic imports
+export function HeavyComponent() {
+  const [Component, setComponent] = useState<React.ComponentType | null>(null);
+
+  useEffect(() => {
+    import("./heavy-charting-library").then((module) => {
+      setComponent(() => module.default);
+    });
+  }, []);
+
+  if (!Component) {
+    return <div>Loading...</div>;
+  }
+
+  return <Component />;
+}
+```
+
+### Tree Shaking
+
+- Use named imports instead of default imports
+- Avoid importing entire libraries
+- Use ES modules for better tree shaking
+- Configure build tools properly
+
+```tsx
+// ✅ Good - Named imports for tree shaking
+import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card";
+import { Button } from "@/components/ui/button";
+import { format, parseISO } from "date-fns";
+
+// ❌ Avoid - Importing entire library
+import * as UI from "@/components/ui";
+import * as dateFns from "date-fns";
+```
+
+## Memory Management
+
+### Memory Leaks Prevention
+
+- Clean up effects properly
+- Remove event listeners
+- Clear intervals and timeouts
+- Handle component unmounting
+
+```tsx
+// ✅ Good - Proper cleanup
+export function SessionTimer({ sessionId }: { sessionId: string }) {
+  const [elapsed, setElapsed] = useState(0);
+  const [isRunning, setIsRunning] = useState(false);
+
+  useEffect(() => {
+    if (!isRunning) return;
+
+    const interval = setInterval(() => {
+      setElapsed((prev) => prev + 1);
+    }, 1000);
+
+    return () => clearInterval(interval);
+  }, [isRunning]);
+
+  useEffect(() => {
+    const handleVisibilityChange = () => {
+      if (document.hidden && isRunning) {
+        // Pause timer when tab is not visible
+        setIsRunning(false);
+      }
+    };
+
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+    return () => {
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+    };
+  }, [isRunning]);
+
+  return <div className="text-lg font-mono">{formatTime(elapsed)}</div>;
+}
+```
+
+### Large Data Handling
+
+- Implement virtual scrolling for large datasets
+- Use pagination for API responses
+- Cache data appropriately
+- Implement data cleanup
+
+```tsx
+// ✅ Good - Large data handling
+export function useVirtualizedSessions(spaceId: string) {
+  const { data: sessions = [] } = useSessionsApi(spaceId);
+
+  const virtualizedData = useMemo(() => {
+    return sessions.map((session, index) => ({
+      id: session.id,
+      data: session,
+      index,
+    }));
+  }, [sessions]);
+
+  return {
+    data: virtualizedData,
+    totalCount: sessions.length,
+  };
+}
+
+// ✅ Good - Data cleanup
+export function useSessionCleanup() {
+  const queryClient = useQueryClient();
+
+  useEffect(() => {
+    const cleanup = () => {
+      // Remove old session data from cache
+      const now = Date.now();
+      const staleTime = 24 * 60 * 60 * 1000; // 24 hours
+
+      queryClient
+        .getQueryCache()
+        .getAll()
+        .forEach((query) => {
+          if (query.queryKey[0] === "sessions") {
+            const lastUpdated = query.state.dataUpdatedAt;
+            if (now - lastUpdated > staleTime) {
+              queryClient.removeQueries({ queryKey: query.queryKey });
+            }
+          }
+        });
+    };
+
+    const interval = setInterval(cleanup, 60 * 60 * 1000); // Run every hour
+    return () => clearInterval(interval);
+  }, [queryClient]);
+}
+```
+
+## Image and Asset Optimization
+
+### Image Optimization
+
+- Use appropriate image formats (WebP, AVIF)
+- Implement lazy loading
+- Provide proper dimensions
+- Use responsive images
+
+```tsx
+// ✅ Good - Optimized images
+export function OptimizedAvatar({ user, size = "md" }: AvatarProps) {
+  const sizeClasses = {
+    sm: "h-8 w-8",
+    md: "h-10 w-10",
+    lg: "h-12 w-12",
+    xl: "h-16 w-16",
+  };
+
+  return (
+    <Avatar className={sizeClasses[size]}>
+      <AvatarImage
+        src={user.avatar_url}
+        alt={`${user.name}'s avatar`}
+        loading="lazy"
+        onError={(e) => {
+          // Fallback to initials if image fails to load
+          e.currentTarget.style.display = "none";
+        }}
+      />
+      <AvatarFallback>
+        {user.name
+          .split(" ")
+          .map((n) => n[0])
+          .join("")}
+      </AvatarFallback>
+    </Avatar>
+  );
+}
+```
+
+### Asset Loading
+
+- Preload critical assets
+- Use appropriate loading strategies
+- Implement proper caching headers
+- Optimize font loading
+
+```tsx
+// ✅ Good - Asset preloading
+export function PreloadCriticalAssets() {
+  useEffect(() => {
+    // Preload critical images
+    const criticalImages = ["/images/logo.svg", "/images/hero-bg.jpg"];
+
+    criticalImages.forEach((src) => {
+      const link = document.createElement("link");
+      link.rel = "preload";
+      link.as = "image";
+      link.href = src;
+      document.head.appendChild(link);
+    });
+
+    // Preload critical fonts
+    const fontLink = document.createElement("link");
+    fontLink.rel = "preload";
+    fontLink.as = "font";
+    fontLink.type = "font/woff2";
+    fontLink.href = "/fonts/inter-var.woff2";
+    fontLink.crossOrigin = "anonymous";
+    document.head.appendChild(fontLink);
+  }, []);
+
+  return null;
+}
+```
+
+## Monitoring and Profiling
+
+### Performance Monitoring
+
+- Use React DevTools Profiler
+- Monitor bundle sizes
+- Track Core Web Vitals
+- Implement performance budgets
+
+```tsx
+// ✅ Good - Performance monitoring
+export function PerformanceMonitor() {
+  useEffect(() => {
+    // Monitor Core Web Vitals
+    if ("web-vital" in window) {
+      import("web-vitals").then(
+        ({ getCLS, getFID, getFCP, getLCP, getTTFB }) => {
+          getCLS(console.log);
+          getFID(console.log);
+          getFCP(console.log);
+          getLCP(console.log);
+          getTTFB(console.log);
+        }
+      );
+    }
+
+    // Monitor React render performance
+    if (process.env.NODE_ENV === "development") {
+      const observer = new PerformanceObserver((list) => {
+        list.getEntries().forEach((entry) => {
+          if (entry.entryType === "measure") {
+            console.log(`${entry.name}: ${entry.duration}ms`);
+          }
+        });
+      });
+      observer.observe({ entryTypes: ["measure"] });
+    }
+  }, []);
+
+  return null;
+}
+```
+
+### Bundle Analysis
+
+- Use webpack-bundle-analyzer
+- Monitor chunk sizes
+- Identify duplicate dependencies
+- Optimize imports
+
+```tsx
+// ✅ Good - Bundle size monitoring
+export function BundleSizeMonitor() {
+  useEffect(() => {
+    if (process.env.NODE_ENV === "development") {
+      // Monitor bundle size in development
+      const script = document.createElement("script");
+      script.src = "https://unpkg.com/webpack-bundle-analyzer/lib/viewer.js";
+      script.onload = () => {
+        console.log("Bundle analyzer loaded");
+      };
+      document.head.appendChild(script);
+    }
+  }, []);
+
+  return null;
+}
+```
diff --git a/.cursor/rules/React-TypeScript-Best-Practices.mdc b/.cursor/rules/React-TypeScript-Best-Practices.mdc
new file mode 100644
index 0000000..7da571d
--- /dev/null
+++ b/.cursor/rules/React-TypeScript-Best-Practices.mdc
@@ -0,0 +1,188 @@
+---
+alwaysApply: true
+---
+
+# React + TypeScript Best Practices for AgileSpace
+
+## Component Structure
+
+Define props with interfaces/types, not prop-types:
+
+```tsx
+interface SessionCardProps {
+  session: Session;
+  onEndSession?: (sessionId: string) => void;
+  onEditSession?: (session: Session) => void;
+}
+
+export function SessionCard({
+  session,
+  onEndSession,
+  onEditSession,
+}: SessionCardProps) {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>{session.title}</CardTitle>
+      </CardHeader>
+    </Card>
+  );
+}
+```
+
+## Component Declaration
+
+Use the function keyword for components:
+
+```tsx
+// ✅ Good
+export function SpaceSidebar({ space }: SpaceSidebarProps) {
+  return <div>...</div>;
+}
+
+// ❌ Avoid
+export const SpaceSidebar = ({ space }: SpaceSidebarProps) => {
+  return <div>...</div>;
+};
+```
+
+## Hooks Usage
+
+- Call hooks only at the top level of components
+- Extract reusable logic into custom hooks with `use-*` prefix
+- Use `use-*-api` prefix for data fetching hooks
+
+```tsx
+// ✅ Good - Custom hooks
+export function useSessions(spaceId: string) {
+  return useQuery({
+    queryKey: ["sessions", spaceId],
+    queryFn: () => getSessions(spaceId),
+  });
+}
+
+// ✅ Good - API hooks
+export function useSessionsApi(spaceId: string) {
+  return useQuery({
+    queryKey: ["sessions", spaceId],
+    queryFn: () =>
+      supabase.from("sessions").select("*").eq("space_id", spaceId),
+  });
+}
+```
+
+## Performance Optimization
+
+- Memoize with React.memo, useCallback, useMemo where appropriate
+- Avoid inline functions in JSX—pull handlers out or wrap in useCallback
+- Use React.lazy + Suspense for code splitting
+
+```tsx
+// ✅ Good - Memoized component
+export const SessionList = React.memo(function SessionList({
+  sessions,
+}: SessionListProps) {
+  return (
+    <div>
+      {sessions.map((session) => (
+        <SessionCard key={session.id} session={session} />
+      ))}
+    </div>
+  );
+});
+
+// ✅ Good - Memoized callback
+const handleEndSession = useCallback(
+  (sessionId: string) => {
+    endSessionMutation.mutate(sessionId);
+  },
+  [endSessionMutation]
+);
+```
+
+## Composition Patterns
+
+- Favor composition (render props, children) over inheritance
+- Use Radix UI components for consistent design system
+- Leverage TanStack Query for data fetching and caching
+
+```tsx
+// ✅ Good - Composition with children
+export function Card({ children, className }: CardProps) {
+  return (
+    <div
+      className={cn(
+        "rounded-lg border bg-card text-card-foreground shadow-sm",
+        className
+      )}
+    >
+      {children}
+    </div>
+  );
+}
+```
+
+## Error Handling
+
+- Implement error boundaries for component error handling
+- Use TanStack Query error states for API errors
+- Provide clear, user-friendly error messages
+
+```tsx
+// ✅ Good - Error boundary
+export function ErrorBoundary({ children }: { children: React.ReactNode }) {
+  return (
+    <ErrorBoundary fallback={<div>Something went wrong</div>}>
+      {children}
+    </ErrorBoundary>
+  );
+}
+
+// ✅ Good - Query error handling
+const { data, error, isLoading } = useSessionsApi(spaceId);
+
+if (error) {
+  return <div>Failed to load sessions: {error.message}</div>;
+}
+```
+
+## Form Handling
+
+- Use react-hook-form with zod validation
+- Prefer controlled components for forms
+- Separate client-side and server-side validation
+
+```tsx
+// ✅ Good - Form with validation
+const form = useForm<SessionFormData>({
+  resolver: zodResolver(sessionSchema),
+  defaultValues: {
+    title: "",
+    description: "",
+  },
+});
+```
+
+## Cleanup and Effects
+
+- Clean up effects in useEffect to prevent leaks
+- Use guard clauses (early returns) for error handling
+- Handle loading states properly
+
+```tsx
+// ✅ Good - Effect with cleanup
+useEffect(() => {
+  const interval = setInterval(() => {
+    updateTimer();
+  }, 1000);
+
+  return () => clearInterval(interval);
+}, [updateTimer]);
+```
+
+## File Organization
+
+- Export components as named exports
+- Keep components focused and single-purpose
+- Use descriptive names with auxiliary verbs (e.g., isLoading, hasError)
+- File layout: exported component → subcomponents → hooks/helpers → static content
diff --git a/.cursor/rules/State-Management.mdc b/.cursor/rules/State-Management.mdc
new file mode 100644
index 0000000..4cdc9ae
--- /dev/null
+++ b/.cursor/rules/State-Management.mdc
@@ -0,0 +1,330 @@
+---
+alwaysApply: true
+---
+
+# State Management for AgileSpace
+
+## State Management Strategy
+
+### Local State (useState/useReducer)
+
+- Use for component-specific state
+- Keep state as close to where it's used as possible
+- Lift state up only when needed for sibling components
+
+```tsx
+// ✅ Good - Local state for component
+function SessionForm() {
+  const [title, setTitle] = useState("");
+  const [description, setDescription] = useState("");
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  // Component logic
+}
+```
+
+### Server State (TanStack Query)
+
+- Use for all API data fetching and caching
+- Leverage TanStack Query for automatic background updates
+- Use mutations for data modifications
+
+```tsx
+// ✅ Good - Server state with TanStack Query
+function useSessionsApi(spaceId: string) {
+  return useQuery({
+    queryKey: ["sessions", spaceId],
+    queryFn: () =>
+      supabase.from("sessions").select("*").eq("space_id", spaceId),
+    staleTime: 5 * 60 * 1000, // 5 minutes
+    gcTime: 10 * 60 * 1000, // 10 minutes
+  });
+}
+
+// ✅ Good - Mutations
+function useCreateSessionApi() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (sessionData: SessionInsert) =>
+      supabase.from("sessions").insert(sessionData).select().single(),
+    onSuccess: (newSession) => {
+      queryClient.invalidateQueries({ queryKey: ["sessions"] });
+      queryClient.setQueryData(
+        ["sessions", newSession.space_id],
+        (old: Session[] = []) => [...old, newSession]
+      );
+    },
+  });
+}
+```
+
+### Global State (Context + useReducer)
+
+- Use React Context for app-wide state that doesn't change frequently
+- Prefer useReducer for complex state logic
+- Keep context providers at the top level
+
+```tsx
+// ✅ Good - Global state with Context
+interface AppState {
+  currentSpace: Space | null;
+  user: User | null;
+  theme: "light" | "dark";
+}
+
+type AppAction =
+  | { type: "SET_CURRENT_SPACE"; payload: Space }
+  | { type: "SET_USER"; payload: User }
+  | { type: "SET_THEME"; payload: "light" | "dark" };
+
+const AppContext = createContext<{
+  state: AppState;
+  dispatch: Dispatch<AppAction>;
+} | null>(null);
+
+export function AppProvider({ children }: { children: React.ReactNode }) {
+  const [state, dispatch] = useReducer(appReducer, initialState);
+
+  return (
+    <AppContext.Provider value={{ state, dispatch }}>
+      {children}
+    </AppContext.Provider>
+  );
+}
+```
+
+## State Organization
+
+### Component State
+
+- Keep state minimal and focused
+- Use descriptive state variable names
+- Group related state in objects
+
+```tsx
+// ✅ Good - Organized component state
+function SessionTimer({ sessionId }: { sessionId: string }) {
+  const [timerState, setTimerState] = useState({
+    isRunning: false,
+    startTime: null as Date | null,
+    elapsed: 0,
+  });
+
+  const [displayState, setDisplayState] = useState({
+    showMilliseconds: false,
+    format: "minutes" as "minutes" | "hours",
+  });
+}
+```
+
+### Form State
+
+- Use react-hook-form for complex forms
+- Leverage zod for validation
+- Keep form state separate from component state
+
+```tsx
+// ✅ Good - Form state with react-hook-form
+const sessionSchema = z.object({
+  title: z.string().min(1, "Title is required"),
+  description: z.string().optional(),
+  track_id: z.string().optional(),
+  tags: z.array(z.string()).optional(),
+});
+
+function SessionForm() {
+  const form = useForm<z.infer<typeof sessionSchema>>({
+    resolver: zodResolver(sessionSchema),
+    defaultValues: {
+      title: "",
+      description: "",
+      tags: [],
+    },
+  });
+}
+```
+
+## State Updates
+
+### Immutable Updates
+
+- Always create new objects/arrays when updating state
+- Use spread operator for shallow updates
+- Use immer for complex updates if needed
+
+```tsx
+// ✅ Good - Immutable state updates
+function updateSession(sessionId: string, updates: Partial<Session>) {
+  setSessions((prev) =>
+    prev.map((session) =>
+      session.id === sessionId ? { ...session, ...updates } : session
+    )
+  );
+}
+
+// ✅ Good - Array updates
+function addTag(sessionId: string, tag: Tag) {
+  setSessions((prev) =>
+    prev.map((session) =>
+      session.id === sessionId
+        ? { ...session, tags: [...session.tags, tag] }
+        : session
+    )
+  );
+}
+```
+
+### Optimistic Updates
+
+- Use optimistic updates for better UX
+- Revert on error
+- Sync with server state
+
+```tsx
+// ✅ Good - Optimistic updates
+function useOptimisticSessionUpdate() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: updateSessionApi,
+    onMutate: async (updatedSession) => {
+      // Cancel outgoing refetches
+      await queryClient.cancelQueries({ queryKey: ["sessions"] });
+
+      // Snapshot previous value
+      const previousSessions = queryClient.getQueryData(["sessions"]);
+
+      // Optimistically update
+      queryClient.setQueryData(["sessions"], (old: Session[] = []) =>
+        old.map((session) =>
+          session.id === updatedSession.id
+            ? { ...session, ...updatedSession }
+            : session
+        )
+      );
+
+      return { previousSessions };
+    },
+    onError: (err, newSession, context) => {
+      // Revert on error
+      queryClient.setQueryData(["sessions"], context?.previousSessions);
+    },
+    onSettled: () => {
+      // Always refetch after error or success
+      queryClient.invalidateQueries({ queryKey: ["sessions"] });
+    },
+  });
+}
+```
+
+## State Persistence
+
+### Local Storage
+
+- Use for user preferences and settings
+- Don't store sensitive data
+- Handle storage errors gracefully
+
+```tsx
+// ✅ Good - Local storage hook
+function useLocalStorage<T>(key: string, initialValue: T) {
+  const [storedValue, setStoredValue] = useState<T>(() => {
+    try {
+      const item = window.localStorage.getItem(key);
+      return item ? JSON.parse(item) : initialValue;
+    } catch (error) {
+      console.error(`Error reading localStorage key "${key}":`, error);
+      return initialValue;
+    }
+  });
+
+  const setValue = (value: T | ((val: T) => T)) => {
+    try {
+      const valueToStore =
+        value instanceof Function ? value(storedValue) : value;
+      setStoredValue(valueToStore);
+      window.localStorage.setItem(key, JSON.stringify(valueToStore));
+    } catch (error) {
+      console.error(`Error setting localStorage key "${key}":`, error);
+    }
+  };
+
+  return [storedValue, setValue] as const;
+}
+```
+
+### URL State
+
+- Use URL parameters for shareable state
+- Keep URL state minimal
+- Use TanStack Router for URL state management
+
+```tsx
+// ✅ Good - URL state with TanStack Router
+function useUrlState() {
+  const navigate = useNavigate();
+  const search = useSearch();
+
+  const updateUrlState = (updates: Record<string, string>) => {
+    navigate({
+      search: (prev) => ({ ...prev, ...updates }),
+    });
+  };
+
+  return { search, updateUrlState };
+}
+```
+
+## Performance Considerations
+
+### State Memoization
+
+- Memoize expensive state computations
+- Use useMemo for derived state
+- Avoid unnecessary re-renders
+
+```tsx
+// ✅ Good - Memoized derived state
+function SessionList({ sessions }: { sessions: Session[] }) {
+  const activeSessions = useMemo(
+    () => sessions.filter((session) => !session.end_time),
+    [sessions]
+  );
+
+  const completedSessions = useMemo(
+    () => sessions.filter((session) => session.end_time),
+    [sessions]
+  );
+
+  const totalDuration = useMemo(
+    () =>
+      completedSessions.reduce((total, session) => {
+        const duration =
+          new Date(session.end_time!).getTime() -
+          new Date(session.start_time).getTime();
+        return total + duration;
+      }, 0),
+    [completedSessions]
+  );
+}
+```
+
+### State Splitting
+
+- Split large state objects into smaller pieces
+- Use multiple contexts for different concerns
+- Avoid prop drilling with context
+
+```tsx
+// ✅ Good - Split contexts
+const AuthContext = createContext<AuthState | null>(null);
+const SpaceContext = createContext<SpaceState | null>(null);
+const ThemeContext = createContext<ThemeState | null>(null);
+
+// Use specific contexts where needed
+function SpaceComponent() {
+  const spaceState = useContext(SpaceContext);
+  // Only re-renders when space state changes
+}
+```
diff --git a/.cursor/rules/TypeScript-Configuration.mdc b/.cursor/rules/TypeScript-Configuration.mdc
new file mode 100644
index 0000000..aee4374
--- /dev/null
+++ b/.cursor/rules/TypeScript-Configuration.mdc
@@ -0,0 +1,222 @@
+---
+alwaysApply: true
+---
+
+# TypeScript Configuration for AgileSpace
+
+## Strict Type Checking
+
+Enable strict mode in tsconfig.json:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  }
+}
+```
+
+## Type Definitions
+
+- Explicitly type function returns and object literals
+- Define interfaces for all data structures
+- Use generic types where appropriate
+- Avoid `any` type usage
+
+```tsx
+// ✅ Good - Explicit typing
+interface Session {
+  id: string;
+  title: string;
+  description?: string;
+  start_time: string;
+  end_time?: string;
+  space_id: string;
+  member_id: string;
+}
+
+// ✅ Good - Function with explicit return type
+function formatDuration(startTime: string, endTime?: string): string {
+  if (!endTime) return "In progress";
+  const duration = new Date(endTime).getTime() - new Date(startTime).getTime();
+  return `${Math.floor(duration / 1000 / 60)} minutes`;
+}
+
+// ✅ Good - Generic types
+function useQuery<T>(queryKey: string[], queryFn: () => Promise<T>) {
+  // Implementation
+}
+```
+
+## Database Types
+
+- Use Supabase generated types from `src/types/database.types.ts`
+- Create custom types that extend database types when needed
+- Export all types from `src/types/index.ts`
+
+```tsx
+// ✅ Good - Using database types
+import type { Database } from "@/types/database.types";
+
+type Session = Database["public"]["Tables"]["sessions"]["Row"];
+type SessionInsert = Database["public"]["Tables"]["sessions"]["Insert"];
+type SessionUpdate = Database["public"]["Tables"]["sessions"]["Update"];
+
+// ✅ Good - Custom types extending database types
+interface SessionWithRelations extends Session {
+  member: Profile;
+  tags: Tag[];
+  track?: Track;
+}
+```
+
+## Error Handling
+
+- Minimize use of `@ts-ignore`/`@ts-expect-error`
+- Use proper error types for API responses
+- Handle nullable values explicitly
+
+```tsx
+// ✅ Good - Proper error handling
+interface ApiResponse<T> {
+  data: T | null;
+  error: string | null;
+}
+
+function handleApiResponse<T>(response: ApiResponse<T>): T {
+  if (response.error) {
+    throw new Error(response.error);
+  }
+  if (!response.data) {
+    throw new Error("No data received");
+  }
+  return response.data;
+}
+
+// ✅ Good - Nullable handling
+function getSessionTitle(session: Session | null): string {
+  return session?.title ?? "Untitled Session";
+}
+```
+
+## Component Props
+
+- Use interfaces for component props
+- Make optional props explicit with `?`
+- Use union types for variant props
+
+```tsx
+// ✅ Good - Component props interface
+interface ButtonProps {
+  variant?:
+    | "default"
+    | "destructive"
+    | "outline"
+    | "secondary"
+    | "ghost"
+    | "link";
+  size?: "default" | "sm" | "lg" | "icon";
+  children: React.ReactNode;
+  onClick?: () => void;
+  disabled?: boolean;
+  className?: string;
+}
+
+// ✅ Good - Union types for variants
+type ButtonVariant =
+  | "default"
+  | "destructive"
+  | "outline"
+  | "secondary"
+  | "ghost"
+  | "link";
+type ButtonSize = "default" | "sm" | "lg" | "icon";
+```
+
+## Hook Types
+
+- Type custom hooks properly
+- Use generic types for reusable hooks
+- Return proper types from hooks
+
+```tsx
+// ✅ Good - Typed custom hook
+function useSessions<T = Session>(
+  spaceId: string
+): {
+  data: T[] | undefined;
+  isLoading: boolean;
+  error: Error | null;
+  refetch: () => void;
+} {
+  return useQuery({
+    queryKey: ["sessions", spaceId],
+    queryFn: () => getSessions(spaceId),
+  });
+}
+
+// ✅ Good - Generic hook
+function useApiQuery<T>(
+  queryKey: string[],
+  queryFn: () => Promise<T>
+): {
+  data: T | undefined;
+  isLoading: boolean;
+  error: Error | null;
+} {
+  return useQuery({ queryKey, queryFn });
+}
+```
+
+## Event Handlers
+
+- Type event handlers properly
+- Use React's built-in event types
+- Handle form events correctly
+
+```tsx
+// ✅ Good - Typed event handlers
+function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
+  event.preventDefault();
+  // Handle form submission
+}
+
+function handleInputChange(event: React.ChangeEvent<HTMLInputElement>) {
+  const { name, value } = event.target;
+  // Handle input change
+}
+
+function handleClick(event: React.MouseEvent<HTMLButtonElement>) {
+  event.preventDefault();
+  // Handle button click
+}
+```
+
+## Utility Types
+
+- Use TypeScript utility types effectively
+- Create custom utility types when needed
+- Leverage mapped types for complex scenarios
+
+```tsx
+// ✅ Good - Utility types
+type PartialSession = Partial<Session>;
+type SessionKeys = keyof Session;
+type SessionValues = Session[SessionKeys];
+
+// ✅ Good - Custom utility types
+type WithId<T> = T & { id: string };
+type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+// ✅ Good - Mapped types
+type SessionFormData = {
+  [K in keyof Session as K extends "id" | "created_at" | "updated_at"
+    ? never
+    : K]: Session[K];
+};
+```
diff --git a/.cursor/rules/UI-Styling.mdc b/.cursor/rules/UI-Styling.mdc
new file mode 100644
index 0000000..bd40fd7
--- /dev/null
+++ b/.cursor/rules/UI-Styling.mdc
@@ -0,0 +1,457 @@
+---
+alwaysApply: true
+---
+
+# UI & Styling for AgileSpace
+
+## Design System
+
+### Tailwind CSS
+
+- Use Tailwind CSS utility classes for styling
+- Leverage the design system tokens and spacing
+- Use semantic color classes (bg-primary, text-muted-foreground)
+- Follow responsive design patterns
+
+```tsx
+// ✅ Good - Tailwind CSS usage
+export function SessionCard({ session }: SessionCardProps) {
+  return (
+    <div className="rounded-lg border bg-card text-card-foreground shadow-sm">
+      <div className="p-6">
+        <h3 className="text-lg font-semibold text-foreground">
+          {session.title}
+        </h3>
+        <p className="text-sm text-muted-foreground mt-2">
+          {session.description}
+        </p>
+        <div className="flex items-center justify-between mt-4">
+          <span className="text-xs text-muted-foreground">
+            {formatDate(session.start_time)}
+          </span>
+          <Badge
+            variant={session.status === "active" ? "default" : "secondary"}
+          >
+            {session.status}
+          </Badge>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### Radix UI Components
+
+- Use Radix UI components for consistent, accessible UI
+- Leverage the shadcn/ui component library
+- Customize components using Tailwind CSS classes
+- Maintain accessibility standards
+
+```tsx
+// ✅ Good - Radix UI components
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+
+export function SessionDialog({ session, onSave }: SessionDialogProps) {
+  return (
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button variant="outline">Edit Session</Button>
+      </DialogTrigger>
+      <DialogContent className="sm:max-w-[425px]">
+        <DialogHeader>
+          <DialogTitle>Edit Session</DialogTitle>
+        </DialogHeader>
+        <div className="grid gap-4 py-4">
+          <div className="grid grid-cols-4 items-center gap-4">
+            <Label htmlFor="title" className="text-right">
+              Title
+            </Label>
+            <Input
+              id="title"
+              defaultValue={session.title}
+              className="col-span-3"
+            />
+          </div>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+## Component Styling
+
+### Class Organization
+
+- Use the `cn` utility for conditional classes
+- Group related classes together
+- Use semantic class names when possible
+- Keep component styling consistent
+
+```tsx
+// ✅ Good - Class organization
+import { cn } from "@/lib/utils";
+
+export function Button({
+  variant = "default",
+  size = "default",
+  className,
+  ...props
+}: ButtonProps) {
+  return (
+    <button
+      className={cn(
+        // Base styles
+        "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+        "disabled:pointer-events-none disabled:opacity-50",
+
+        // Variant styles
+        variant === "default" &&
+          "bg-primary text-primary-foreground hover:bg-primary/90",
+        variant === "destructive" &&
+          "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+        variant === "outline" &&
+          "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        variant === "secondary" &&
+          "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        variant === "ghost" && "hover:bg-accent hover:text-accent-foreground",
+        variant === "link" && "text-primary underline-offset-4 hover:underline",
+
+        // Size styles
+        size === "default" && "h-10 px-4 py-2",
+        size === "sm" && "h-9 rounded-md px-3",
+        size === "lg" && "h-11 rounded-md px-8",
+        size === "icon" && "h-10 w-10",
+
+        // Custom classes
+        className
+      )}
+      {...props}
+    />
+  );
+}
+```
+
+### Responsive Design
+
+- Use Tailwind's responsive prefixes (sm:, md:, lg:, xl:)
+- Design mobile-first
+- Test on different screen sizes
+- Use appropriate breakpoints
+
+```tsx
+// ✅ Good - Responsive design
+export function SessionList({ sessions }: SessionListProps) {
+  return (
+    <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
+      {sessions.map((session) => (
+        <SessionCard key={session.id} session={session} />
+      ))}
+    </div>
+  );
+}
+
+// ✅ Good - Responsive layout
+export function DashboardLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="min-h-screen bg-background">
+      <div className="flex">
+        {/* Sidebar - hidden on mobile, visible on desktop */}
+        <aside className="hidden md:flex w-64 flex-col border-r bg-background">
+          <SpaceSidebar />
+        </aside>
+
+        {/* Main content */}
+        <main className="flex-1 p-4 md:p-6">{children}</main>
+      </div>
+    </div>
+  );
+}
+```
+
+## Color System
+
+### Semantic Colors
+
+- Use semantic color tokens for consistency
+- Leverage the theme system for dark/light mode
+- Use appropriate contrast ratios
+- Follow accessibility guidelines
+
+```tsx
+// ✅ Good - Semantic colors
+export function StatusBadge({
+  status,
+}: {
+  status: "active" | "completed" | "paused";
+}) {
+  const statusConfig = {
+    active: {
+      className: "bg-green-100 text-green-800 border-green-200",
+      label: "Active",
+    },
+    completed: {
+      className: "bg-blue-100 text-blue-800 border-blue-200",
+      label: "Completed",
+    },
+    paused: {
+      className: "bg-yellow-100 text-yellow-800 border-yellow-200",
+      label: "Paused",
+    },
+  };
+
+  const config = statusConfig[status];
+
+  return (
+    <span
+      className={cn(
+        "inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-medium",
+        config.className
+      )}
+    >
+      {config.label}
+    </span>
+  );
+}
+```
+
+### Theme Support
+
+- Support both light and dark themes
+- Use CSS variables for theme colors
+- Test both themes thoroughly
+- Provide smooth theme transitions
+
+```tsx
+// ✅ Good - Theme-aware components
+export function ThemeToggle() {
+  const { theme, setTheme } = useTheme();
+
+  return (
+    <Button
+      variant="ghost"
+      size="icon"
+      onClick={() => setTheme(theme === "light" ? "dark" : "light")}
+    >
+      <Sun className="h-[1.2rem] w-[1.2rem] rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
+      <Moon className="absolute h-[1.2rem] w-[1.2rem] rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
+      <span className="sr-only">Toggle theme</span>
+    </Button>
+  );
+}
+```
+
+## Layout Patterns
+
+### Grid and Flexbox
+
+- Use CSS Grid for two-dimensional layouts
+- Use Flexbox for one-dimensional layouts
+- Combine both for complex layouts
+- Use appropriate gap spacing
+
+```tsx
+// ✅ Good - Layout patterns
+export function DashboardGrid() {
+  return (
+    <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
+      {/* Stats cards */}
+      <div className="lg:col-span-2 grid grid-cols-1 sm:grid-cols-2 gap-4">
+        <StatsCard title="Active Sessions" value="5" />
+        <StatsCard title="Total Time" value="2h 30m" />
+        <StatsCard title="Completed Tasks" value="12" />
+        <StatsCard title="Team Members" value="8" />
+      </div>
+
+      {/* Sidebar */}
+      <div className="space-y-4">
+        <ActiveMembers />
+        <RecentActivity />
+      </div>
+    </div>
+  );
+}
+```
+
+### Spacing System
+
+- Use consistent spacing tokens
+- Follow the 4px base unit system
+- Use appropriate spacing for different contexts
+- Maintain visual hierarchy
+
+```tsx
+// ✅ Good - Consistent spacing
+export function SessionForm() {
+  return (
+    <div className="space-y-6">
+      <div className="space-y-2">
+        <Label htmlFor="title">Session Title</Label>
+        <Input id="title" placeholder="Enter session title" />
+      </div>
+
+      <div className="space-y-2">
+        <Label htmlFor="description">Description</Label>
+        <Textarea
+          id="description"
+          placeholder="Enter session description"
+          className="min-h-[100px]"
+        />
+      </div>
+
+      <div className="flex items-center justify-end space-x-2">
+        <Button variant="outline">Cancel</Button>
+        <Button>Save Session</Button>
+      </div>
+    </div>
+  );
+}
+```
+
+## Animation and Transitions
+
+### Micro-interactions
+
+- Use subtle animations for better UX
+- Keep animations fast and purposeful
+- Use Tailwind's transition utilities
+- Respect user preferences (prefers-reduced-motion)
+
+```tsx
+// ✅ Good - Smooth transitions
+export function AnimatedCard({ children, className }: CardProps) {
+  return (
+    <div
+      className={cn(
+        "rounded-lg border bg-card text-card-foreground shadow-sm",
+        "transition-all duration-200 ease-in-out",
+        "hover:shadow-md hover:scale-[1.02]",
+        "focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-2",
+        className
+      )}
+    >
+      {children}
+    </div>
+  );
+}
+```
+
+### Loading States
+
+- Provide clear loading indicators
+- Use skeleton components for content loading
+- Maintain layout stability during loading
+- Use appropriate loading durations
+
+```tsx
+// ✅ Good - Loading states
+export function SessionListSkeleton() {
+  return (
+    <div className="space-y-4">
+      {Array.from({ length: 3 }).map((_, i) => (
+        <div key={i} className="rounded-lg border p-6">
+          <div className="space-y-3">
+            <div className="h-4 bg-muted rounded animate-pulse" />
+            <div className="h-3 bg-muted rounded w-3/4 animate-pulse" />
+            <div className="flex items-center justify-between">
+              <div className="h-3 bg-muted rounded w-1/4 animate-pulse" />
+              <div className="h-6 bg-muted rounded w-16 animate-pulse" />
+            </div>
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Accessibility
+
+### Semantic HTML
+
+- Use appropriate HTML elements
+- Provide proper ARIA attributes
+- Ensure keyboard navigation
+- Maintain focus management
+
+```tsx
+// ✅ Good - Accessible components
+export function AccessibleButton({
+  children,
+  onClick,
+  disabled,
+  "aria-label": ariaLabel,
+  ...props
+}: ButtonProps) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      aria-label={ariaLabel}
+      aria-disabled={disabled}
+      className={cn(
+        "inline-flex items-center justify-center rounded-md text-sm font-medium",
+        "transition-colors focus-visible:outline-none focus-visible:ring-2",
+        "focus-visible:ring-ring focus-visible:ring-offset-2",
+        "disabled:pointer-events-none disabled:opacity-50",
+        props.className
+      )}
+      {...props}
+    >
+      {children}
+    </button>
+  );
+}
+```
+
+### Focus Management
+
+- Ensure logical tab order
+- Provide visible focus indicators
+- Handle focus in modals and dialogs
+- Support screen readers
+
+```tsx
+// ✅ Good - Focus management
+export function Modal({ isOpen, onClose, children }: ModalProps) {
+  const modalRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (isOpen && modalRef.current) {
+      // Focus the first focusable element
+      const firstFocusable = modalRef.current.querySelector(
+        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+      ) as HTMLElement;
+      firstFocusable?.focus();
+    }
+  }, [isOpen]);
+
+  if (!isOpen) return null;
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center">
+      <div className="fixed inset-0 bg-background/80 backdrop-blur-sm" />
+      <div
+        ref={modalRef}
+        className="relative z-50 w-full max-w-lg rounded-lg border bg-background p-6 shadow-lg"
+        role="dialog"
+        aria-modal="true"
+      >
+        {children}
+      </div>
+    </div>
+  );
+}
+```
diff --git a/.gitignore b/.gitignore
index ebed3a1..c182a53 100644
--- a/.gitignore
+++ b/.gitignore
@@ -23,14 +23,21 @@ dist-ssr
 *.sln
 *.sw?
 
+# Environment variables
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
 # Supabase
 .branches
 .temp
-supabase/.env
-supabase/.env.local
-supabase/.env.*.local
+supabase/.branches
+supabase/.temp
 
-# dotenvx
-.env.keys
-.env.local
-.env.*.local
+# Tasks and project management (local only)
+tasks/
+*.task
+*.todo
+project-tasks/

From a013f98b9f256da580cdd0f62101586c120d20a8 Mon Sep 17 00:00:00 2001
From: Mina Sameh <mina.sameh.lameh@gmail.com>
Date: Sat, 19 Jul 2025 04:22:40 +0300
Subject: [PATCH 2/3] feat: implement hierarchical tags system with categories
 and subcategories

- Add database migration for tag hierarchy (parent_id, tag_type, sort_order, is_system)
- Create hierarchical tag management hooks and components
- Implement predefined issue type categories (Meeting, Development, Project Management)
- Add hierarchical tag selector for session creation
- Update end session dialog to use new tag selector
- Add cursor rules for code organization and best practices
- Support system tags with seeding functionality
- Improve tag management UI with collapsible categories
---
 .cursor/rules/agilespace-patterns.mdc         | 111 ++++
 .cursor/rules/custom-hooks-best-practices.mdc | 182 ++++++
 .cursor/rules/separation-of-concerns.mdc      |  96 +++
 .cursor/rules/unused-code-prevention.mdc      | 143 +++++
 src/components/end-session-dialog.tsx         |  49 +-
 src/components/hierarchical-tag-form.tsx      | 181 ++++++
 src/components/hierarchical-tag-selector.tsx  | 157 +++++
 src/constants/issue-types.ts                  | 161 +++++
 src/hooks/api/use-tags.ts                     |  24 +-
 src/hooks/use-hierarchical-tag-management.ts  | 311 ++++++++++
 src/hooks/use-hierarchical-tag-selector.ts    | 104 ++++
 src/lib/supabase/mutations.ts                 | 103 +++-
 src/lib/supabase/queries.ts                   |  49 ++
 src/routes/space/$slug/tags/index.tsx         | 514 ++++++++++------
 src/types/database.types.ts                   | 574 +++++++++---------
 src/types/index.ts                            |  13 +
 .../20250719004549_add_hierarchy_to_tags.sql  |  15 +
 17 files changed, 2282 insertions(+), 505 deletions(-)
 create mode 100644 .cursor/rules/agilespace-patterns.mdc
 create mode 100644 .cursor/rules/custom-hooks-best-practices.mdc
 create mode 100644 .cursor/rules/separation-of-concerns.mdc
 create mode 100644 .cursor/rules/unused-code-prevention.mdc
 create mode 100644 src/components/hierarchical-tag-form.tsx
 create mode 100644 src/components/hierarchical-tag-selector.tsx
 create mode 100644 src/constants/issue-types.ts
 create mode 100644 src/hooks/use-hierarchical-tag-management.ts
 create mode 100644 src/hooks/use-hierarchical-tag-selector.ts
 create mode 100644 supabase/migrations/20250719004549_add_hierarchy_to_tags.sql

diff --git a/.cursor/rules/agilespace-patterns.mdc b/.cursor/rules/agilespace-patterns.mdc
new file mode 100644
index 0000000..a69378b
--- /dev/null
+++ b/.cursor/rules/agilespace-patterns.mdc
@@ -0,0 +1,111 @@
+---
+alwaysApply: true
+---
+
+# AgileSpace Project Patterns
+
+## Architecture Overview
+
+AgileSpace follows a clean architecture with strict separation of concerns:
+
+- **Components**: Pure UI rendering in [src/components/](mdc:src/components/)
+- **Hooks**: Business logic in [src/hooks/](mdc:src/hooks/)
+- **API Layer**: Supabase queries/mutations in [src/lib/supabase/](mdc:src/lib/supabase/)
+- **Types**: TypeScript definitions in [src/types/](mdc:src/types/)
+
+## Required Patterns
+
+### ✅ Component Structure
+
+```tsx
+// src/components/feature-name.tsx
+import { useFeatureName } from "@/hooks/use-feature-name";
+
+export function FeatureName({ prop }: FeatureNameProps) {
+  const { data, loading, handleAction } = useFeatureName({ prop });
+
+  if (loading) return <LoadingSpinner />;
+
+  return <div className="feature-container">{/* UI only */}</div>;
+}
+```
+
+### ✅ Hook Structure
+
+```tsx
+// src/hooks/use-feature-name.ts
+export function useFeatureName({ prop }: UseFeatureNameProps) {
+  // All logic here
+  return { data, loading, actions };
+}
+```
+
+### ✅ API Layer
+
+- Queries in [src/lib/supabase/queries.ts](mdc:src/lib/supabase/queries.ts)
+- Mutations in [src/lib/supabase/mutations.ts](mdc:src/lib/supabase/mutations.ts)
+- Use TanStack Query for data fetching
+
+### ✅ Required Imports
+
+```tsx
+// UI Components
+import { Button } from "@/components/ui/button";
+import { Badge } from "@/components/ui/badge";
+
+// Utils
+import { cn } from "@/lib/utils";
+
+// Types
+import type { Tag, Session } from "@/types";
+```
+
+## AgileSpace-Specific Rules
+
+### Hierarchical Tags Implementation
+
+- Use [useHierarchicalTagSelector](mdc:src/hooks/use-hierarchical-tag-selector.ts) for tag logic
+- Categories and subcategories from [issue-types.ts](mdc:src/constants/issue-types.ts)
+- Seed predefined types with `seedIssueTypes` function
+
+### Session Management
+
+- All session logic in custom hooks
+- Use TanStack Query for session data
+- Handle optimistic updates for better UX
+
+### Styling Conventions
+
+- Use Tailwind CSS utility classes
+- Follow [AgileSpace design system](mdc:src/components/ui/)
+- Ensure accessibility with proper ARIA attributes
+
+### Error Handling
+
+- Use error boundaries for component errors
+- Handle API errors in hooks with TanStack Query
+- Provide user-friendly error messages
+
+## File Organization
+
+```
+src/
+├── components/           # Pure UI components
+│   ├── ui/              # Design system components
+│   └── feature-name.tsx # Feature-specific components
+├── hooks/               # Business logic hooks
+│   ├── api/            # API-related hooks
+│   └── use-*.ts        # Feature hooks
+├── lib/
+│   ├── supabase/       # Database layer
+│   └── utils.ts        # Utility functions
+├── types/              # TypeScript definitions
+└── constants/          # Application constants
+```
+
+## Quality Standards
+
+- **TypeScript**: Strict typing, no `any`
+- **Performance**: Use React.memo, useCallback, useMemo appropriately
+- **Accessibility**: WCAG 2.1 AA compliance
+- **Testing**: Separate logic from UI for better testability
diff --git a/.cursor/rules/custom-hooks-best-practices.mdc b/.cursor/rules/custom-hooks-best-practices.mdc
new file mode 100644
index 0000000..c4ed0f9
--- /dev/null
+++ b/.cursor/rules/custom-hooks-best-practices.mdc
@@ -0,0 +1,182 @@
+---
+alwaysApply: true
+---
+
+# Custom Hooks Best Practices
+
+## Rule: Follow Hook Patterns and Conventions
+
+Custom hooks in [src/hooks/](mdc:src/hooks/) should follow these patterns:
+
+### ✅ Hook Structure:
+
+```tsx
+// File: src/hooks/use-feature-name.ts
+import { useState, useCallback, useEffect } from "react";
+import { useQuery, useMutation } from "@tanstack/react-query";
+
+interface UseFeatureNameProps {
+  required: string;
+  optional?: boolean;
+}
+
+export function useFeatureName({
+  required,
+  optional = false,
+}: UseFeatureNameProps) {
+  // 1. Local state
+  const [localState, setLocalState] = useState(initialValue);
+
+  // 2. Queries and mutations
+  const query = useQuery({
+    queryKey: ["feature", required],
+    queryFn: () => fetchData(required),
+  });
+
+  // 3. Memoized callbacks
+  const handleAction = useCallback(
+    (param: string) => {
+      // Logic here
+    },
+    [dependency]
+  );
+
+  // 4. Utility functions
+  const isSelected = useCallback(
+    (id: string) => {
+      return localState.includes(id);
+    },
+    [localState]
+  );
+
+  // 5. Return object with clear naming
+  return {
+    // Data
+    data: query.data || [],
+    loading: query.isLoading,
+    error: query.error,
+
+    // State
+    localState,
+
+    // Actions
+    handleAction,
+
+    // Utilities
+    isSelected,
+  };
+}
+```
+
+### ✅ Naming Conventions:
+
+- **File names**: `use-feature-name.ts` (kebab-case)
+- **Function names**: `useFeatureName` (camelCase)
+- **Props interface**: `UseFeatureNameProps`
+- **Return clear, descriptive property names**
+
+### ✅ Hook Responsibilities:
+
+- State management
+- API calls and data fetching
+- Business logic and data transformations
+- Event handlers and callbacks
+- Side effects (useEffect)
+- Memoization (useMemo, useCallback)
+
+### ✅ Return Object Organization:
+
+Group returned values logically:
+
+```tsx
+return {
+  // Data from queries
+  data,
+  loading,
+  error,
+
+  // Local state
+  selectedItems,
+  isExpanded,
+
+  // Actions/handlers
+  handleSelect,
+  handleToggle,
+  handleSubmit,
+
+  // Utilities/computed values
+  isSelected,
+  hasSelection,
+  totalCount,
+};
+```
+
+### ❌ Avoid in Hooks:
+
+- JSX rendering
+- Direct DOM manipulation
+- Component-specific styling logic
+- Hardcoded UI strings (use constants)
+
+### Example Hook Patterns:
+
+#### Data Fetching Hook:
+
+```tsx
+export function useApiData(id: string) {
+  const query = useQuery({
+    queryKey: ["data", id],
+    queryFn: () => fetchData(id),
+  });
+
+  return {
+    data: query.data,
+    loading: query.isLoading,
+    error: query.error,
+    refetch: query.refetch,
+  };
+}
+```
+
+#### Form Logic Hook:
+
+```tsx
+export function useFormLogic(initialValues: FormData) {
+  const [values, setValues] = useState(initialValues);
+  const [errors, setErrors] = useState<Record<string, string>>({});
+
+  const handleChange = useCallback(
+    (field: string, value: any) => {
+      setValues((prev) => ({ ...prev, [field]: value }));
+      // Clear error when user types
+      if (errors[field]) {
+        setErrors((prev) => ({ ...prev, [field]: "" }));
+      }
+    },
+    [errors]
+  );
+
+  const validate = useCallback(() => {
+    const newErrors = validateForm(values);
+    setErrors(newErrors);
+    return Object.keys(newErrors).length === 0;
+  }, [values]);
+
+  return {
+    values,
+    errors,
+    handleChange,
+    validate,
+    isValid: Object.keys(errors).length === 0,
+  };
+}
+```
+
+### Benefits:
+
+- Reusable logic across components
+- Better testability
+- Cleaner separation of concerns
+- Easier debugging and maintenance
+
+---
diff --git a/.cursor/rules/separation-of-concerns.mdc b/.cursor/rules/separation-of-concerns.mdc
new file mode 100644
index 0000000..9160999
--- /dev/null
+++ b/.cursor/rules/separation-of-concerns.mdc
@@ -0,0 +1,96 @@
+---
+alwaysApply: true
+---
+
+# Separation of Concerns for React Components
+
+## Rule: Separate UI and Logic
+
+React components in [src/components/](mdc:src/components/) should follow strict separation of concerns:
+
+### ✅ Components Should Only Handle:
+
+- JSX rendering and UI structure
+- Event handlers that call hook functions
+- Conditional rendering based on hook state
+- Styling and accessibility attributes
+
+### ❌ Components Should NOT Handle:
+
+- State management (use custom hooks)
+- API calls or data fetching
+- Complex business logic
+- Side effects (useEffect)
+- Data transformations
+
+### Pattern to Follow:
+
+```tsx
+// ✅ Good - UI Component
+import { useMyFeature } from "@/hooks/use-my-feature";
+
+export function MyComponent({ prop1, prop2 }: MyComponentProps) {
+  const { data, loading, error, handleAction, isSelected } = useMyFeature({
+    prop1,
+    prop2,
+  });
+
+  if (loading) return <LoadingSpinner />;
+  if (error) return <ErrorMessage error={error} />;
+
+  return (
+    <div className="my-component">
+      {data.map((item) => (
+        <button key={item.id} onClick={() => handleAction(item)}>
+          {item.name}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+```tsx
+// ✅ Good - Logic Hook
+export function useMyFeature({ prop1, prop2 }: UseMyFeatureProps) {
+  const [state, setState] = useState(initialState);
+
+  const query = useQuery({
+    queryKey: ["my-feature", prop1],
+    queryFn: () => fetchData(prop1),
+  });
+
+  const handleAction = useCallback((item: Item) => {
+    // Business logic here
+    setState((prevState) => updateState(prevState, item));
+  }, []);
+
+  const isSelected = useCallback(
+    (id: string) => {
+      return state.selectedIds.includes(id);
+    },
+    [state.selectedIds]
+  );
+
+  return {
+    data: query.data || [],
+    loading: query.isLoading,
+    error: query.error,
+    handleAction,
+    isSelected,
+  };
+}
+```
+
+### Custom Hook Naming Convention:
+
+- Use `use-` prefix followed by feature name
+- Store in [src/hooks/](mdc:src/hooks/) directory
+- Export with descriptive TypeScript interfaces
+
+### Benefits:
+
+- Better testability (test logic separately from UI)
+- Reusable logic across components
+- Cleaner, more readable components
+- Easier maintenance and debugging
diff --git a/.cursor/rules/unused-code-prevention.mdc b/.cursor/rules/unused-code-prevention.mdc
new file mode 100644
index 0000000..1f3510e
--- /dev/null
+++ b/.cursor/rules/unused-code-prevention.mdc
@@ -0,0 +1,143 @@
+---
+alwaysApply: true
+description: "Prevent unused code, imports, variables, and functions"
+---
+
+# Unused Code Prevention for AgileSpace
+
+## Rule: Eliminate All Unused Code
+
+This rule enforces strict removal of unused code to maintain a clean, performant, and maintainable codebase.
+
+### ❌ Prohibited: Unused Imports
+
+```tsx
+// ❌ Bad - Unused imports
+import React from "react"; // Not using React
+import { Button, Card } from "@/components/ui"; // Only using Button
+import type { User, Session, Tag } from "@/types"; // Only using User
+
+export function MyComponent({ user }: { user: User }) {
+  return <Button>{user.name}</Button>;
+}
+```
+
+```tsx
+// ✅ Good - Only necessary imports
+import { Button } from "@/components/ui/button";
+import type { User } from "@/types";
+
+export function MyComponent({ user }: { user: User }) {
+  return <Button>{user.name}</Button>;
+}
+```
+
+### ❌ Prohibited: Unused Variables
+
+```tsx
+// ❌ Bad - Unused variables
+export function SessionCard({ session }: SessionCardProps) {
+  const [isLoading, setIsLoading] = useState(false); // Never used
+  const duration = calculateDuration(session.start_time); // Never used
+
+  return <div>{session.title}</div>;
+}
+```
+
+```tsx
+// ✅ Good - Only necessary variables
+export function SessionCard({ session }: SessionCardProps) {
+  return <div>{session.title}</div>;
+}
+```
+
+### ❌ Prohibited: Unused Functions
+
+```tsx
+// ❌ Bad - Unused helper functions
+function formatDuration(ms: number): string {
+  // Never called anywhere
+  return `${ms / 1000}s`;
+}
+
+export function LoginForm() {
+  return <form>...</form>;
+}
+```
+
+```tsx
+// ✅ Good - Only necessary functions
+export function LoginForm() {
+  return <form>...</form>;
+}
+```
+
+### ❌ Prohibited: Unused Hook Returns
+
+```tsx
+// ❌ Bad - Unused hook returns
+export function MyComponent() {
+  const { data, loading, error, refetch } = useQuery(...) // Only using data
+
+  return (
+    <div>
+      {data?.map(item => <div key={item.id}>{item.name}</div>)}
+    </div>
+  )
+}
+```
+
+```tsx
+// ✅ Good - Only destructure what's needed
+export function MyComponent() {
+  const { data } = useQuery(...)
+
+  return (
+    <div>
+      {data?.map(item => <div key={item.id}>{item.name}</div>)}
+    </div>
+  )
+}
+```
+
+## Detection Strategies
+
+### 1. TypeScript Compiler Flags
+
+- Use `"noUnusedLocals": true` in tsconfig.json
+- Use `"noUnusedParameters": true` in tsconfig.json
+- Regular `pnpm tsc --noEmit` checks
+
+### 2. ESLint Rules
+
+- `@typescript-eslint/no-unused-vars`
+- `import/no-unused-modules`
+
+### 3. IDE Integration
+
+- Use VS Code's "Remove Unused Imports" command
+- Enable "Organize Imports on Save"
+- Use "Go to References" to verify usage
+
+## Cleanup Commands
+
+```bash
+# Check for unused code
+pnpm tsc --noEmit
+pnpm eslint src/ --fix
+```
+
+## Benefits
+
+1. **Smaller Bundle Size**: Fewer imports = smaller build output
+2. **Better Performance**: Less code to parse and execute
+3. **Cleaner Codebase**: Easier to read and maintain
+4. **Better Tree Shaking**: Build tools can optimize better
+
+## Enforcement
+
+- **Pre-commit Hooks**: Run unused code checks
+- **CI/CD Pipeline**: Fail builds with unused code
+- **Code Reviews**: Manually check for unused imports/variables
+
+Remember: **Every line of code has a cost**. If it's not providing value, remove it! 🧹
diff --git a/src/components/end-session-dialog.tsx b/src/components/end-session-dialog.tsx
index 291fae0..5033f2e 100644
--- a/src/components/end-session-dialog.tsx
+++ b/src/components/end-session-dialog.tsx
@@ -3,14 +3,11 @@ import { Button } from '@/components/ui/button'
 import { Label } from '@/components/ui/label'
 import { Checkbox } from '@/components/ui/checkbox'
 import { useState, useEffect } from 'react'
-import { getTags } from '@/lib/supabase/queries'
 import type { Tag } from '@/types'
-import { Badge } from '@/components/ui/badge'
-import { X, Eye, Pencil } from 'lucide-react'
-import { cn, isLightColor } from '@/lib/utils'
-import { useQuery } from '@tanstack/react-query'
+import { Eye, Pencil } from 'lucide-react'
 import MDEditor from '@uiw/react-md-editor'
 import { createFireEffect } from '@/lib/celebrate'
+import { HierarchicalTagSelector } from '@/components/hierarchical-tag-selector'
 
 interface EndSessionDialogProps {
     open: boolean
@@ -36,12 +33,6 @@ export function EndSessionDialog({
     const [isPreview, setIsPreview] = useState(false)
     const canSubmit = skipComment || message.trim().length > 0
 
-    const { data: tags = [] } = useQuery({
-        queryKey: ['tags', spaceId],
-        queryFn: () => getTags(spaceId),
-        enabled: open && !!spaceId
-    })
-
     useEffect(() => {
         if (!open) {
             setSkipComment(false)
@@ -60,14 +51,6 @@ export function EndSessionDialog({
         };
     }, [open]);
 
-    const toggleTag = (tag: Tag) => {
-        setSelectedTags(prev =>
-            prev.some(t => t.id === tag.id)
-                ? prev.filter(t => t.id !== tag.id)
-                : [...prev, tag]
-        )
-    }
-
     const handleEndSession = () => {
         onEndSession(skipComment, selectedTags);
         createFireEffect();
@@ -114,28 +97,12 @@ export function EndSessionDialog({
                             className="!bg-transparent [&_.w-md-editor]:!bg-transparent [&_.w-md-editor-toolbar]:!bg-transparent [&_.w-md-editor-toolbar-divider]:!bg-border [&_.w-md-editor-toolbar-button]:!text-foreground [&_.w-md-editor-toolbar-button]:hover:!bg-accent [&_.w-md-editor-toolbar-button]:hover:!text-accent-foreground [&_.w-md-editor-text-pre]:!text-foreground [&_.w-md-editor-text-input]:!text-foreground"
                         />
                     </div>
-                    <div className="space-y-2">
-                        <Label>Session Type</Label>
-                        <div className="flex flex-wrap gap-2">
-                            {tags.map(tag => (
-                                <Badge
-                                    key={tag.id}
-                                    variant={selectedTags.some(t => t.id === tag.id) ? "default" : "outline"}
-                                    className={cn(
-                                        "cursor-pointer",
-                                        selectedTags.some(t => t.id === tag.id) && tag.color && isLightColor(tag.color) ? "text-gray-900" : undefined
-                                    )}
-                                    style={{ backgroundColor: selectedTags.some(t => t.id === tag.id) && tag.color ? tag.color : undefined }}
-                                    onClick={() => toggleTag(tag)}
-                                >
-                                    {tag.name}
-                                    {selectedTags.some(t => t.id === tag.id) && (
-                                        <X className="ml-1 h-3 w-3" />
-                                    )}
-                                </Badge>
-                            ))}
-                        </div>
-                    </div>
+                    <HierarchicalTagSelector
+                        spaceId={spaceId}
+                        selectedTags={selectedTags}
+                        onTagsChange={setSelectedTags}
+                        disabled={isPending}
+                    />
                     <div className="flex items-center space-x-2">
                         <Checkbox
                             id="skip-comment"
diff --git a/src/components/hierarchical-tag-form.tsx b/src/components/hierarchical-tag-form.tsx
new file mode 100644
index 0000000..4af1c22
--- /dev/null
+++ b/src/components/hierarchical-tag-form.tsx
@@ -0,0 +1,181 @@
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
+import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";
+import { Alert, AlertDescription } from "@/components/ui/alert";
+import { AlertCircle } from "lucide-react";
+import { cn } from "@/lib/utils";
+import type { Tag, TagType } from "@/types";
+
+interface TagFormData {
+    name: string;
+    color: string;
+    tagType: TagType;
+    parentId?: string;
+    sortOrder?: number;
+}
+
+interface HierarchicalTagFormProps {
+    formData: TagFormData;
+    categories: Tag[];
+    onFormDataChange: (updates: Partial<TagFormData>) => void;
+    onSubmit: (e: React.FormEvent) => void;
+    isSubmitting: boolean;
+    submitButtonText: string;
+    error?: Error | null;
+    mode: "create" | "edit";
+}
+
+export function HierarchicalTagForm({
+    formData,
+    categories,
+    onFormDataChange,
+    onSubmit,
+    isSubmitting,
+    submitButtonText,
+    error,
+    mode,
+}: HierarchicalTagFormProps) {
+    const isCategory = formData.tagType === "category";
+    const requiresParent = formData.tagType === "subcategory";
+
+    return (
+        <form onSubmit={onSubmit} className="space-y-6">
+            {/* Tag Type Selection */}
+            <div className="space-y-3">
+                <Label>Tag Type</Label>
+                <RadioGroup
+                    value={formData.tagType}
+                    onValueChange={(value: TagType) => onFormDataChange({ tagType: value, parentId: undefined })}
+                    className="flex space-x-6"
+                >
+                    <div className="flex items-center space-x-2">
+                        <RadioGroupItem value="category" id="category" />
+                        <Label htmlFor="category" className="font-normal">
+                            Category
+                        </Label>
+                    </div>
+                    <div className="flex items-center space-x-2">
+                        <RadioGroupItem value="subcategory" id="subcategory" />
+                        <Label htmlFor="subcategory" className="font-normal">
+                            Subcategory
+                        </Label>
+                    </div>
+                </RadioGroup>
+                <p className="text-sm text-muted-foreground">
+                    {isCategory
+                        ? "Categories are top-level groupings for organizing issue types"
+                        : "Subcategories are specific issue types within a category"}
+                </p>
+            </div>
+
+            {/* Parent Category Selection (for subcategories) */}
+            {requiresParent && (
+                <div className="space-y-2">
+                    <Label htmlFor="parentCategory">Parent Category *</Label>
+                    <Select
+                        value={formData.parentId || ""}
+                        onValueChange={(value) => onFormDataChange({ parentId: value })}
+                    >
+                        <SelectTrigger>
+                            <SelectValue placeholder="Select a parent category" />
+                        </SelectTrigger>
+                        <SelectContent>
+                            {categories.map((category) => (
+                                <SelectItem key={category.id} value={category.id}>
+                                    <div className="flex items-center space-x-2">
+                                        <div
+                                            className="w-3 h-3 rounded-full"
+                                            style={{ backgroundColor: category.color || "#6B7280" }}
+                                        />
+                                        <span>{category.name}</span>
+                                    </div>
+                                </SelectItem>
+                            ))}
+                        </SelectContent>
+                    </Select>
+                    {requiresParent && !formData.parentId && (
+                        <p className="text-sm text-destructive">Please select a parent category</p>
+                    )}
+                </div>
+            )}
+
+            {/* Tag Name */}
+            <div className="space-y-2">
+                <Label htmlFor="tagName">Name *</Label>
+                <Input
+                    id="tagName"
+                    value={formData.name}
+                    onChange={(e) => onFormDataChange({ name: e.target.value })}
+                    placeholder={`Enter ${formData.tagType} name`}
+                    className={cn(!formData.name.trim() && "border-destructive")}
+                />
+                {!formData.name.trim() && (
+                    <p className="text-sm text-destructive">Name is required</p>
+                )}
+            </div>
+
+            {/* Tag Color */}
+            <div className="space-y-2">
+                <Label htmlFor="tagColor">Color</Label>
+                <div className="flex items-center space-x-3">
+                    <Input
+                        type="color"
+                        id="tagColor"
+                        value={formData.color}
+                        onChange={(e) => onFormDataChange({ color: e.target.value })}
+                        className="w-16 h-10 p-1 border rounded cursor-pointer"
+                    />
+                    <Input
+                        type="text"
+                        value={formData.color}
+                        onChange={(e) => onFormDataChange({ color: e.target.value })}
+                        placeholder="#3B82F6"
+                        className="flex-1"
+                    />
+                </div>
+            </div>
+
+            {/* Sort Order */}
+            <div className="space-y-2">
+                <Label htmlFor="sortOrder">Sort Order</Label>
+                <Input
+                    type="number"
+                    id="sortOrder"
+                    value={formData.sortOrder || 0}
+                    onChange={(e) => onFormDataChange({ sortOrder: parseInt(e.target.value) || 0 })}
+                    placeholder="0"
+                    min="0"
+                    className="w-24"
+                />
+                <p className="text-sm text-muted-foreground">
+                    Lower numbers appear first in lists
+                </p>
+            </div>
+
+            {/* Error Display */}
+            {error && (
+                <Alert variant="destructive">
+                    <AlertCircle className="h-4 w-4" />
+                    <AlertDescription>
+                        {error instanceof Error ? error.message : "An error occurred"}
+                    </AlertDescription>
+                </Alert>
+            )}
+
+            {/* Submit Button */}
+            <Button
+                type="submit"
+                className="w-full"
+                disabled={
+                    isSubmitting ||
+                    !formData.name.trim() ||
+                    (requiresParent && !formData.parentId)
+                }
+            >
+                {isSubmitting ? "Saving..." : submitButtonText}
+            </Button>
+        </form>
+    );
+} 
diff --git a/src/components/hierarchical-tag-selector.tsx b/src/components/hierarchical-tag-selector.tsx
new file mode 100644
index 0000000..091f441
--- /dev/null
+++ b/src/components/hierarchical-tag-selector.tsx
@@ -0,0 +1,157 @@
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { Label } from "@/components/ui/label";
+import { cn, isLightColor } from "@/lib/utils";
+import { X, ChevronRight, ChevronDown } from "lucide-react";
+import { useHierarchicalTagSelector } from "@/hooks/use-hierarchical-tag-selector";
+import type { Tag } from "@/types";
+
+interface HierarchicalTagSelectorProps {
+    spaceId: string;
+    selectedTags: Tag[];
+    onTagsChange: (tags: Tag[]) => void;
+    disabled?: boolean;
+}
+
+export function HierarchicalTagSelector({
+    spaceId,
+    selectedTags,
+    onTagsChange,
+    disabled = false,
+}: HierarchicalTagSelectorProps) {
+    const {
+        selectedCategory,
+        categories,
+        categoriesLoading,
+        handleCategorySelect,
+        toggleTag,
+        removeTag,
+        getSubcategoriesQuery,
+        isTagSelected,
+        isCategoryExpanded,
+    } = useHierarchicalTagSelector({
+        spaceId,
+        selectedTags,
+        onTagsChange,
+    });
+
+    if (categoriesLoading) {
+        return (
+            <div className="space-y-4">
+                <div>
+                    <Label>Issue Type</Label>
+                    <p className="text-sm text-muted-foreground">Loading categories...</p>
+                </div>
+            </div>
+        );
+    }
+
+    return (
+        <div className="space-y-4">
+            <div>
+                <Label>Issue Type</Label>
+                <p className="text-sm text-muted-foreground">
+                    Select a category and then choose specific issue types
+                </p>
+            </div>
+
+            {/* Selected tags display */}
+            {selectedTags.length > 0 && (
+                <div className="space-y-2">
+                    <Label className="text-sm">Selected:</Label>
+                    <div className="flex flex-wrap gap-2">
+                        {selectedTags.map((tag) => (
+                            <Badge
+                                key={tag.id}
+                                variant="default"
+                                className={cn(
+                                    "cursor-pointer",
+                                    tag.color && isLightColor(tag.color) ? "text-gray-900" : "text-white"
+                                )}
+                                style={{ backgroundColor: tag.color || undefined }}
+                                onClick={() => removeTag(tag.id)}
+                            >
+                                {tag.name}
+                                <X className="ml-1 h-3 w-3" />
+                            </Badge>
+                        ))}
+                    </div>
+                </div>
+            )}
+
+            {/* Category and subcategory selection */}
+            <div className="space-y-3">
+                {categories.map((category) => {
+                    const isExpanded = isCategoryExpanded(category.id);
+                    const categorySubcategories = getSubcategoriesQuery(category.id);
+
+                    return (
+                        <div key={category.id} className="space-y-2">
+                            {/* Category button */}
+                            <Button
+                                variant="outline"
+                                size="sm"
+                                disabled={disabled}
+                                onClick={() => handleCategorySelect(category)}
+                                className={cn(
+                                    "w-full justify-start",
+                                    selectedCategory?.id === category.id && "ring-2 ring-primary"
+                                )}
+                            >
+                                <div
+                                    className="w-3 h-3 rounded-full mr-2"
+                                    style={{ backgroundColor: category.color || "#6B7280" }}
+                                />
+                                {isExpanded ? (
+                                    <ChevronDown className="w-4 h-4 mr-2" />
+                                ) : (
+                                    <ChevronRight className="w-4 h-4 mr-2" />
+                                )}
+                                {category.name}
+                            </Button>
+
+                            {/* Subcategories */}
+                            {isExpanded && (
+                                <div className="ml-4 space-y-1">
+                                    {categorySubcategories.isLoading && (
+                                        <p className="text-sm text-muted-foreground">Loading...</p>
+                                    )}
+                                    {categorySubcategories.data?.map((subcategory) => {
+                                        const isSelected = isTagSelected(subcategory.id);
+                                        return (
+                                            <Badge
+                                                key={subcategory.id}
+                                                variant={isSelected ? "default" : "outline"}
+                                                className={cn(
+                                                    "cursor-pointer mr-2 mb-1",
+                                                    isSelected && subcategory.color && isLightColor(subcategory.color)
+                                                        ? "text-gray-900"
+                                                        : undefined
+                                                )}
+                                                style={{
+                                                    backgroundColor:
+                                                        isSelected && subcategory.color ? subcategory.color : undefined,
+                                                }}
+                                                onClick={() => !disabled && toggleTag(subcategory)}
+                                            >
+                                                {subcategory.name}
+                                                {isSelected && <X className="ml-1 h-3 w-3" />}
+                                            </Badge>
+                                        );
+                                    })}
+                                </div>
+                            )}
+                        </div>
+                    );
+                })}
+            </div>
+
+            {categories.length === 0 && (
+                <div className="text-center py-6 text-muted-foreground">
+                    <p>No issue types available.</p>
+                    <p className="text-sm">Contact your administrator to set up issue types.</p>
+                </div>
+            )}
+        </div>
+    );
+} 
diff --git a/src/constants/issue-types.ts b/src/constants/issue-types.ts
new file mode 100644
index 0000000..e355822
--- /dev/null
+++ b/src/constants/issue-types.ts
@@ -0,0 +1,161 @@
+export interface IssueTypeCategory {
+  name: string;
+  color: string;
+  description: string;
+  children: IssueTypeSubcategory[];
+}
+
+export interface IssueTypeSubcategory {
+  name: string;
+  color: string;
+  description: string;
+}
+
+export const ISSUE_TYPE_HIERARCHY: Record<string, IssueTypeCategory> = {
+  Meeting: {
+    name: "Meeting",
+    color: "#3B82F6",
+    description: "Various types of meetings and discussions",
+    children: [
+      { name: "Demo", color: "#10B981", description: "Product demonstrations" },
+      {
+        name: "Daily Stand-up",
+        color: "#F59E0B",
+        description: "Daily team sync meetings",
+      },
+      {
+        name: "Retrospective",
+        color: "#EF4444",
+        description: "Sprint retrospectives",
+      },
+      {
+        name: "Sprint Planning",
+        color: "#8B5CF6",
+        description: "Sprint planning sessions",
+      },
+      {
+        name: "Backlog Refinement",
+        color: "#06B6D4",
+        description: "Backlog grooming sessions",
+      },
+      {
+        name: "Design Review",
+        color: "#84CC16",
+        description: "Design review meetings",
+      },
+      {
+        name: "Technical Planning",
+        color: "#F97316",
+        description: "Technical planning sessions",
+      },
+      {
+        name: "Casual Meeting",
+        color: "#6B7280",
+        description: "Informal discussions",
+      },
+      {
+        name: "PM Follow-up and Sync",
+        color: "#EC4899",
+        description: "PM sync meetings",
+      },
+    ],
+  },
+  Development: {
+    name: "Development",
+    color: "#059669",
+    description: "Development and technical work",
+    children: [
+      {
+        name: "Bugs",
+        color: "#DC2626",
+        description: "Bug fixes and debugging",
+      },
+      {
+        name: "Feature Development",
+        color: "#2563EB",
+        description: "New feature development",
+      },
+      {
+        name: "Code Review",
+        color: "#7C3AED",
+        description: "Code review activities",
+      },
+      { name: "Testing", color: "#D97706", description: "Testing and QA work" },
+      {
+        name: "Documentation",
+        color: "#059669",
+        description: "Documentation writing",
+      },
+    ],
+  },
+  "Project Management": {
+    name: "Project Management",
+    color: "#7C2D12",
+    description: "Project management activities",
+    children: [
+      { name: "Scrum", color: "#1E40AF", description: "Scrum ceremonies" },
+      {
+        name: "Product Issues",
+        color: "#BE185D",
+        description: "Product-related issues",
+      },
+      {
+        name: "Planning",
+        color: "#0891B2",
+        description: "Project planning activities",
+      },
+      {
+        name: "Coordination",
+        color: "#7C3AED",
+        description: "Team coordination tasks",
+      },
+    ],
+  },
+};
+
+// Helper function to get all categories
+export function getCategories(): string[] {
+  return Object.keys(ISSUE_TYPE_HIERARCHY);
+}
+
+// Helper function to get subcategories for a category
+export function getSubcategories(category: string): IssueTypeSubcategory[] {
+  return ISSUE_TYPE_HIERARCHY[category]?.children || [];
+}
+
+// Helper function to get category data
+export function getCategory(category: string): IssueTypeCategory | undefined {
+  return ISSUE_TYPE_HIERARCHY[category];
+}
+
+// Helper function to find subcategory within a category
+export function findSubcategory(
+  category: string,
+  subcategoryName: string
+): IssueTypeSubcategory | undefined {
+  return ISSUE_TYPE_HIERARCHY[category]?.children.find(
+    (sub) => sub.name === subcategoryName
+  );
+}
+
+// Helper function to get all issue types as flat array
+export function getAllIssueTypes(): Array<{
+  category: string;
+  subcategory: IssueTypeSubcategory;
+}> {
+  const result: Array<{
+    category: string;
+    subcategory: IssueTypeSubcategory;
+  }> = [];
+
+  Object.entries(ISSUE_TYPE_HIERARCHY).forEach(([categoryName, category]) => {
+    category.children.forEach((subcategory) => {
+      result.push({
+        category: categoryName,
+        subcategory,
+      });
+    });
+  });
+
+  return result;
+}
diff --git a/src/hooks/api/use-tags.ts b/src/hooks/api/use-tags.ts
index afac3b2..b72e347 100644
--- a/src/hooks/api/use-tags.ts
+++ b/src/hooks/api/use-tags.ts
@@ -1,7 +1,12 @@
 import { useState } from "react";
 import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
-import { getTags } from "@/lib/supabase/queries";
-import { createTag, deleteTag, updateTag } from "@/lib/supabase/mutations";
+import { getTags, getHierarchicalTags } from "@/lib/supabase/queries";
+import {
+  createTag,
+  deleteTag,
+  updateTag,
+  seedIssueTypes,
+} from "@/lib/supabase/mutations";
 import type { Tag } from "@/types";
 
 export function useTags(spaceId: string | undefined) {
@@ -49,6 +54,14 @@ export function useTags(spaceId: string | undefined) {
     },
   });
 
+  const seedIssueTypesMutation = useMutation({
+    mutationFn: () => seedIssueTypes(spaceId!),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["tags", spaceId] });
+      queryClient.invalidateQueries({ queryKey: ["categories", spaceId] });
+    },
+  });
+
   const handleCreateTag = (e: React.FormEvent) => {
     e.preventDefault();
     if (!spaceId || !newTagName.trim()) return;
@@ -59,6 +72,11 @@ export function useTags(spaceId: string | undefined) {
     updateTagMutation.mutate({ id, updates });
   };
 
+  const handleSeedIssueTypes = () => {
+    if (!spaceId) return;
+    seedIssueTypesMutation.mutate();
+  };
+
   return {
     tags,
     isLoading,
@@ -76,7 +94,9 @@ export function useTags(spaceId: string | undefined) {
     createTagMutation,
     updateTagMutation,
     deleteTagMutation,
+    seedIssueTypesMutation,
     handleCreateTag,
     handleUpdateTag,
+    handleSeedIssueTypes,
   };
 }
diff --git a/src/hooks/use-hierarchical-tag-management.ts b/src/hooks/use-hierarchical-tag-management.ts
new file mode 100644
index 0000000..0f2ba0b
--- /dev/null
+++ b/src/hooks/use-hierarchical-tag-management.ts
@@ -0,0 +1,311 @@
+import { useState, useMemo } from "react";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import {
+  getTags,
+  getCategoryTags,
+  getHierarchicalTags,
+} from "@/lib/supabase/queries";
+import {
+  createCategoryTag,
+  createSubcategoryTag,
+  updateTag,
+  deleteTag,
+  seedIssueTypes,
+} from "@/lib/supabase/mutations";
+import type { Tag, TagType } from "@/types";
+
+interface TagFormData {
+  name: string;
+  color: string;
+  tagType: TagType;
+  parentId?: string;
+  sortOrder?: number;
+}
+
+export function useHierarchicalTagManagement(spaceId: string | undefined) {
+  const queryClient = useQueryClient();
+
+  // Form states
+  const [isCreateDialogOpen, setIsCreateDialogOpen] = useState(false);
+  const [isEditDialogOpen, setIsEditDialogOpen] = useState(false);
+  const [editingTag, setEditingTag] = useState<Tag | null>(null);
+
+  // Form data
+  const [formData, setFormData] = useState<TagFormData>({
+    name: "",
+    color: "#3B82F6",
+    tagType: "subcategory",
+    parentId: undefined,
+    sortOrder: 0,
+  });
+
+  // Fetch all tags
+  const tagsQuery = useQuery({
+    queryKey: ["tags", spaceId],
+    queryFn: () => getTags(spaceId!),
+    enabled: !!spaceId,
+  });
+
+  // Fetch categories for parent selection
+  const categoriesQuery = useQuery({
+    queryKey: ["categories", spaceId],
+    queryFn: () => getCategoryTags(spaceId!),
+    enabled: !!spaceId,
+  });
+
+  // Fetch hierarchical tags for display
+  const hierarchicalTagsQuery = useQuery({
+    queryKey: ["hierarchical-tags", spaceId],
+    queryFn: () => getHierarchicalTags(spaceId!),
+    enabled: !!spaceId,
+  });
+
+  // Create tag mutation
+  const createTagMutation = useMutation({
+    mutationFn: async (data: TagFormData) => {
+      if (!spaceId) throw new Error("Space ID is required");
+
+      if (data.tagType === "category") {
+        return createCategoryTag(
+          spaceId,
+          data.name,
+          data.color,
+          data.sortOrder || 0,
+          false
+        );
+      } else {
+        if (!data.parentId)
+          throw new Error("Parent category is required for subcategories");
+        return createSubcategoryTag(
+          spaceId,
+          data.name,
+          data.color,
+          data.parentId,
+          data.sortOrder || 0,
+          false
+        );
+      }
+    },
+    onSuccess: () => {
+      // Invalidate all tag-related queries
+      queryClient.invalidateQueries({ queryKey: ["tags", spaceId] });
+      queryClient.invalidateQueries({ queryKey: ["categories", spaceId] });
+      queryClient.invalidateQueries({
+        queryKey: ["hierarchical-tags", spaceId],
+      });
+
+      // Reset form
+      resetForm();
+      setIsCreateDialogOpen(false);
+    },
+  });
+
+  // Update tag mutation
+  const updateTagMutation = useMutation({
+    mutationFn: async ({
+      id,
+      updates,
+    }: {
+      id: string;
+      updates: Partial<TagFormData>;
+    }) => {
+      const updateData: Partial<Tag> = {};
+
+      if (updates.name) updateData.name = updates.name;
+      if (updates.color) updateData.color = updates.color;
+      if (updates.tagType) updateData.tag_type = updates.tagType;
+      if (updates.parentId !== undefined)
+        updateData.parent_id = updates.parentId;
+      if (updates.sortOrder !== undefined)
+        updateData.sort_order = updates.sortOrder;
+
+      return updateTag(id, updateData);
+    },
+    onSuccess: () => {
+      // Invalidate all tag-related queries
+      queryClient.invalidateQueries({ queryKey: ["tags", spaceId] });
+      queryClient.invalidateQueries({ queryKey: ["categories", spaceId] });
+      queryClient.invalidateQueries({
+        queryKey: ["hierarchical-tags", spaceId],
+      });
+
+      // Reset editing state
+      setEditingTag(null);
+      setIsEditDialogOpen(false);
+    },
+  });
+
+  // Delete tag mutation
+  const deleteTagMutation = useMutation({
+    mutationFn: deleteTag,
+    onSuccess: () => {
+      // Invalidate all tag-related queries
+      queryClient.invalidateQueries({ queryKey: ["tags", spaceId] });
+      queryClient.invalidateQueries({ queryKey: ["categories", spaceId] });
+      queryClient.invalidateQueries({
+        queryKey: ["hierarchical-tags", spaceId],
+      });
+    },
+  });
+
+  // Seed issue types mutation
+  const seedIssueTypesMutation = useMutation({
+    mutationFn: () => seedIssueTypes(spaceId!),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["tags", spaceId] });
+      queryClient.invalidateQueries({ queryKey: ["categories", spaceId] });
+      queryClient.invalidateQueries({
+        queryKey: ["hierarchical-tags", spaceId],
+      });
+    },
+  });
+
+  // Helper functions
+  const resetForm = () => {
+    setFormData({
+      name: "",
+      color: "#3B82F6",
+      tagType: "subcategory",
+      parentId: undefined,
+      sortOrder: 0,
+    });
+  };
+
+  const openCreateDialog = (
+    tagType: TagType = "subcategory",
+    parentId?: string
+  ) => {
+    resetForm();
+    setFormData((prev) => ({
+      ...prev,
+      tagType,
+      parentId,
+    }));
+    setIsCreateDialogOpen(true);
+  };
+
+  const openEditDialog = (tag: Tag) => {
+    setEditingTag(tag);
+    setFormData({
+      name: tag.name,
+      color: tag.color || "#3B82F6",
+      tagType: (tag.tag_type as TagType) || "subcategory",
+      parentId: tag.parent_id || undefined,
+      sortOrder: tag.sort_order || 0,
+    });
+    setIsEditDialogOpen(true);
+  };
+
+  const closeDialogs = () => {
+    setIsCreateDialogOpen(false);
+    setIsEditDialogOpen(false);
+    setEditingTag(null);
+    resetForm();
+  };
+
+  const updateFormData = (updates: Partial<TagFormData>) => {
+    setFormData((prev) => ({ ...prev, ...updates }));
+  };
+
+  const handleCreateSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!formData.name.trim()) return;
+    createTagMutation.mutate(formData);
+  };
+
+  const handleEditSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!editingTag || !formData.name.trim()) return;
+    updateTagMutation.mutate({ id: editingTag.id, updates: formData });
+  };
+
+  const handleDelete = (tagId: string) => {
+    deleteTagMutation.mutate(tagId);
+  };
+
+  const handleSeedIssueTypes = () => {
+    if (!spaceId) return;
+    seedIssueTypesMutation.mutate();
+  };
+
+  // Group tags by category - LOGIC belongs in hook
+  const groupedTags = useMemo(() => {
+    const categoryMap = new Map<
+      string,
+      { category: Tag; subcategories: Tag[] }
+    >();
+
+    // Initialize categories
+    categoriesQuery.data?.forEach((category) => {
+      categoryMap.set(category.id, {
+        category,
+        subcategories: [],
+      });
+    });
+
+    // Add subcategories to their parent categories
+    tagsQuery.data
+      ?.filter((tag) => tag.parent_id)
+      .forEach((subcategory) => {
+        const parentId = subcategory.parent_id!;
+        if (categoryMap.has(parentId)) {
+          categoryMap.get(parentId)!.subcategories.push(subcategory);
+        }
+      });
+
+    // Sort subcategories by sort_order and name
+    categoryMap.forEach((group) => {
+      group.subcategories.sort((a, b) => {
+        const orderA = a.sort_order || 0;
+        const orderB = b.sort_order || 0;
+        if (orderA !== orderB) return orderA - orderB;
+        return a.name.localeCompare(b.name);
+      });
+    });
+
+    return Array.from(categoryMap.values()).sort((a, b) => {
+      const orderA = a.category.sort_order || 0;
+      const orderB = b.category.sort_order || 0;
+      if (orderA !== orderB) return orderA - orderB;
+      return a.category.name.localeCompare(b.category.name);
+    });
+  }, [categoriesQuery.data, tagsQuery.data]);
+
+  return {
+    // Data
+    tags: tagsQuery.data || [],
+    categories: categoriesQuery.data || [],
+    groupedTags, // Add grouped tags to return object
+    hierarchicalTags: hierarchicalTagsQuery.data || [],
+
+    // Loading states
+    isLoading: tagsQuery.isLoading,
+    isCreating: createTagMutation.isPending,
+    isUpdating: updateTagMutation.isPending,
+    isDeleting: deleteTagMutation.isPending,
+    isSeeding: seedIssueTypesMutation.isPending,
+
+    // Error states
+    error: tagsQuery.error,
+    createError: createTagMutation.error,
+    updateError: updateTagMutation.error,
+
+    // Dialog states
+    isCreateDialogOpen,
+    isEditDialogOpen,
+    editingTag,
+
+    // Form data
+    formData,
+
+    // Actions
+    openCreateDialog,
+    openEditDialog,
+    closeDialogs,
+    updateFormData,
+    handleCreateSubmit,
+    handleEditSubmit,
+    handleDelete,
+    handleSeedIssueTypes,
+  };
+}
diff --git a/src/hooks/use-hierarchical-tag-selector.ts b/src/hooks/use-hierarchical-tag-selector.ts
new file mode 100644
index 0000000..75d14f5
--- /dev/null
+++ b/src/hooks/use-hierarchical-tag-selector.ts
@@ -0,0 +1,104 @@
+import { useState } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { getCategoryTags, getSubcategoryTags } from "@/lib/supabase/queries";
+import type { Tag } from "@/types";
+
+interface UseHierarchicalTagSelectorProps {
+  spaceId: string;
+  selectedTags: Tag[];
+  onTagsChange: (tags: Tag[]) => void;
+}
+
+export function useHierarchicalTagSelector({
+  spaceId,
+  selectedTags,
+  onTagsChange,
+}: UseHierarchicalTagSelectorProps) {
+  const [selectedCategory, setSelectedCategory] = useState<Tag | null>(null);
+  const [expandedCategories, setExpandedCategories] = useState<Set<string>>(
+    new Set()
+  );
+
+  // Fetch categories
+  const categoriesQuery = useQuery({
+    queryKey: ["categories", spaceId],
+    queryFn: () => getCategoryTags(spaceId),
+    enabled: !!spaceId,
+  });
+
+  // Get subcategories for a specific category
+  const getSubcategoriesQuery = (categoryId: string) => {
+    return useQuery({
+      queryKey: ["subcategories", spaceId, categoryId],
+      queryFn: () => getSubcategoryTags(spaceId, categoryId),
+      enabled: expandedCategories.has(categoryId),
+    });
+  };
+
+  // Toggle category expansion
+  const toggleCategoryExpansion = (categoryId: string) => {
+    const newExpanded = new Set(expandedCategories);
+    if (newExpanded.has(categoryId)) {
+      newExpanded.delete(categoryId);
+    } else {
+      newExpanded.add(categoryId);
+    }
+    setExpandedCategories(newExpanded);
+  };
+
+  // Handle category selection
+  const handleCategorySelect = (category: Tag) => {
+    if (selectedCategory?.id === category.id) {
+      setSelectedCategory(null);
+    } else {
+      setSelectedCategory(category);
+      toggleCategoryExpansion(category.id);
+    }
+  };
+
+  // Handle tag toggle (for subcategories)
+  const toggleTag = (tag: Tag) => {
+    const isSelected = selectedTags.some((t) => t.id === tag.id);
+    if (isSelected) {
+      onTagsChange(selectedTags.filter((t) => t.id !== tag.id));
+    } else {
+      onTagsChange([...selectedTags, tag]);
+    }
+  };
+
+  // Remove selected tag
+  const removeTag = (tagId: string) => {
+    onTagsChange(selectedTags.filter((t) => t.id !== tagId));
+  };
+
+  // Check if a tag is selected
+  const isTagSelected = (tagId: string) => {
+    return selectedTags.some((t) => t.id === tagId);
+  };
+
+  // Check if a category is expanded
+  const isCategoryExpanded = (categoryId: string) => {
+    return expandedCategories.has(categoryId);
+  };
+
+  return {
+    // State
+    selectedCategory,
+    expandedCategories,
+
+    // Data
+    categories: categoriesQuery.data || [],
+    categoriesLoading: categoriesQuery.isLoading,
+    categoriesError: categoriesQuery.error,
+
+    // Actions
+    handleCategorySelect,
+    toggleTag,
+    removeTag,
+
+    // Utilities
+    getSubcategoriesQuery,
+    isTagSelected,
+    isCategoryExpanded,
+  };
+}
diff --git a/src/lib/supabase/mutations.ts b/src/lib/supabase/mutations.ts
index 55f044c..7e59978 100644
--- a/src/lib/supabase/mutations.ts
+++ b/src/lib/supabase/mutations.ts
@@ -211,10 +211,26 @@ export async function deleteSession(sessionId: string) {
   if (error) throw new Error(error.message);
 }
 
-export async function createTag(spaceId: string, name: string, color?: string) {
+export async function createTag(
+  spaceId: string,
+  name: string,
+  color?: string,
+  parentId?: string,
+  tagType: "category" | "subcategory" = "subcategory",
+  sortOrder: number = 0,
+  isSystem: boolean = false
+) {
   const { data, error } = await supabase
     .from("tags")
-    .insert({ space_id: spaceId, name, color })
+    .insert({
+      space_id: spaceId,
+      name,
+      color,
+      parent_id: parentId,
+      tag_type: tagType,
+      sort_order: sortOrder,
+      is_system: isSystem,
+    })
     .select()
     .single();
 
@@ -222,9 +238,50 @@ export async function createTag(spaceId: string, name: string, color?: string) {
   return data as Tag;
 }
 
+// Create a category tag
+export async function createCategoryTag(
+  spaceId: string,
+  name: string,
+  color: string,
+  sortOrder: number = 0,
+  isSystem: boolean = false
+) {
+  return createTag(
+    spaceId,
+    name,
+    color,
+    undefined,
+    "category",
+    sortOrder,
+    isSystem
+  );
+}
+
+// Create a subcategory tag
+export async function createSubcategoryTag(
+  spaceId: string,
+  name: string,
+  color: string,
+  parentId: string,
+  sortOrder: number = 0,
+  isSystem: boolean = false
+) {
+  return createTag(
+    spaceId,
+    name,
+    color,
+    parentId,
+    "subcategory",
+    sortOrder,
+    isSystem
+  );
+}
+
 export async function updateTag(
   id: string,
-  updates: Partial<Pick<Tag, "name" | "color">>
+  updates: Partial<
+    Pick<Tag, "name" | "color" | "parent_id" | "tag_type" | "sort_order">
+  >
 ) {
   const { data, error } = await supabase
     .from("tags")
@@ -237,6 +294,46 @@ export async function updateTag(
   return data as Tag;
 }
 
+// Seed predefined issue types for a space
+export async function seedIssueTypes(spaceId: string) {
+  const { ISSUE_TYPE_HIERARCHY } = await import("@/constants/issue-types");
+
+  const createdTags: Tag[] = [];
+
+  // Create categories first
+  let categoryOrder = 0;
+  for (const [categoryName, categoryData] of Object.entries(
+    ISSUE_TYPE_HIERARCHY
+  )) {
+    const category = await createCategoryTag(
+      spaceId,
+      categoryData.name,
+      categoryData.color,
+      categoryOrder,
+      true // is_system
+    );
+    createdTags.push(category);
+
+    // Create subcategories
+    let subcategoryOrder = 0;
+    for (const subcategory of categoryData.children) {
+      const subcategoryTag = await createSubcategoryTag(
+        spaceId,
+        subcategory.name,
+        subcategory.color,
+        category.id,
+        subcategoryOrder,
+        true // is_system
+      );
+      createdTags.push(subcategoryTag);
+      subcategoryOrder++;
+    }
+    categoryOrder++;
+  }
+
+  return createdTags;
+}
+
 export async function deleteTag(id: string) {
   const { error } = await supabase.from("tags").delete().eq("id", id);
 
diff --git a/src/lib/supabase/queries.ts b/src/lib/supabase/queries.ts
index f4ebf3b..6414130 100644
--- a/src/lib/supabase/queries.ts
+++ b/src/lib/supabase/queries.ts
@@ -488,6 +488,55 @@ export async function getTags(spaceId: string) {
     .from("tags")
     .select("*")
     .eq("space_id", spaceId)
+    .order("sort_order", { ascending: true })
+    .order("name");
+
+  if (error) throw error;
+  return data || [];
+}
+
+// Get hierarchical tags with parent-child relationships
+export async function getHierarchicalTags(spaceId: string) {
+  const { data, error } = await supabase
+    .from("tags")
+    .select(
+      `
+      *,
+      parent:parent_id(*),
+      children:tags!parent_id(*)
+    `
+    )
+    .eq("space_id", spaceId)
+    .order("sort_order", { ascending: true })
+    .order("name");
+
+  if (error) throw error;
+  return data || [];
+}
+
+// Get only category tags (parent tags)
+export async function getCategoryTags(spaceId: string) {
+  const { data, error } = await supabase
+    .from("tags")
+    .select("*")
+    .eq("space_id", spaceId)
+    .eq("tag_type", "category")
+    .order("sort_order", { ascending: true })
+    .order("name");
+
+  if (error) throw error;
+  return data || [];
+}
+
+// Get subcategory tags for a specific category
+export async function getSubcategoryTags(spaceId: string, parentId: string) {
+  const { data, error } = await supabase
+    .from("tags")
+    .select("*")
+    .eq("space_id", spaceId)
+    .eq("parent_id", parentId)
+    .eq("tag_type", "subcategory")
+    .order("sort_order", { ascending: true })
     .order("name");
 
   if (error) throw error;
diff --git a/src/routes/space/$slug/tags/index.tsx b/src/routes/space/$slug/tags/index.tsx
index 0442775..b71af42 100644
--- a/src/routes/space/$slug/tags/index.tsx
+++ b/src/routes/space/$slug/tags/index.tsx
@@ -1,8 +1,6 @@
 import { createFileRoute } from '@tanstack/react-router'
 import { getSpaceAndTracks } from '@/lib/supabase/queries'
 import { Button } from '@/components/ui/button'
-import { Input } from '@/components/ui/input'
-import { Label } from '@/components/ui/label'
 import {
     Table,
     TableBody,
@@ -16,7 +14,6 @@ import {
     DialogContent,
     DialogHeader,
     DialogTitle,
-    DialogTrigger,
 } from '@/components/ui/dialog'
 import {
     AlertDialog,
@@ -29,9 +26,18 @@ import {
     AlertDialogTitle,
     AlertDialogTrigger,
 } from '@/components/ui/alert-dialog'
-import { Pencil, Trash2, Plus } from 'lucide-react'
+import {
+    DropdownMenu,
+    DropdownMenuContent,
+    DropdownMenuItem,
+    DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu'
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@/components/ui/collapsible'
+import { Pencil, Trash2, Plus, FolderPlus, TagIcon, ChevronDown, ChevronRight } from 'lucide-react'
 import { TagsListSkeleton } from '@/components/skeleton/tags-list-skeleton'
-import { useTags } from '@/hooks/api/use-tags'
+import { HierarchicalTagForm } from '@/components/hierarchical-tag-form'
+import { useHierarchicalTagManagement } from '@/hooks/use-hierarchical-tag-management'
+import { useState } from 'react'
 
 export const Route = createFileRoute('/space/$slug/tags/')({
     component: TagsPage,
@@ -42,26 +48,52 @@ export const Route = createFileRoute('/space/$slug/tags/')({
 
 function TagsPage() {
     const { space } = Route.useLoaderData()
+    const [expandedCategories, setExpandedCategories] = useState<Set<string>>(new Set())
+
     const {
         tags,
+        categories,
+        groupedTags, // Get from hook instead of computing in UI
         isLoading,
         error,
-        newTagName,
-        setNewTagName,
-        newTagColor,
-        setNewTagColor,
-        editingTag,
-        setEditingTag,
+        isCreating,
+        isUpdating,
+        isDeleting,
+        isSeeding,
+        createError,
+        updateError,
         isCreateDialogOpen,
-        setIsCreateDialogOpen,
-        editingTagId,
-        setEditingTagId,
-        createTagMutation,
-        updateTagMutation,
-        deleteTagMutation,
-        handleCreateTag,
-        handleUpdateTag,
-    } = useTags(space?.id)
+        isEditDialogOpen,
+        editingTag,
+        formData,
+        openCreateDialog,
+        openEditDialog,
+        closeDialogs,
+        updateFormData,
+        handleCreateSubmit,
+        handleEditSubmit,
+        handleDelete,
+        handleSeedIssueTypes,
+    } = useHierarchicalTagManagement(space?.id)
+
+    // UI-only functions for expand/collapse
+    const toggleCategory = (categoryId: string) => {
+        const newExpanded = new Set(expandedCategories)
+        if (newExpanded.has(categoryId)) {
+            newExpanded.delete(categoryId)
+        } else {
+            newExpanded.add(categoryId)
+        }
+        setExpandedCategories(newExpanded)
+    }
+
+    const expandAll = () => {
+        setExpandedCategories(new Set(categories.map(c => c.id)))
+    }
+
+    const collapseAll = () => {
+        setExpandedCategories(new Set())
+    }
 
     if (!space) {
         return (
@@ -75,9 +107,7 @@ function TagsPage() {
     }
 
     if (isLoading) {
-        return (
-            <TagsListSkeleton />
-        )
+        return <TagsListSkeleton />
     }
 
     if (error) {
@@ -95,172 +125,294 @@ function TagsPage() {
         <div className="space-y-6">
             <div className="flex items-center justify-between">
                 <h1 className="text-3xl font-bold">Tags</h1>
-                <Dialog open={isCreateDialogOpen} onOpenChange={setIsCreateDialogOpen}>
-                    <DialogTrigger asChild>
-                        <Button>
-                            <Plus className="h-4 w-4 mr-2" />
-                            Create Tag
+                <div className="flex gap-2">
+                    {tags.length === 0 && (
+                        <Button
+                            variant="outline"
+                            onClick={handleSeedIssueTypes}
+                            disabled={isSeeding}
+                        >
+                            {isSeeding ? 'Seeding...' : 'Seed Issue Types'}
                         </Button>
-                    </DialogTrigger>
-                    <DialogContent>
-                        <DialogHeader>
-                            <DialogTitle>Create New Tag</DialogTitle>
-                        </DialogHeader>
-                        <form onSubmit={handleCreateTag} className="space-y-4">
-                            <div className="space-y-2">
-                                <Label htmlFor="tagName">Name</Label>
-                                <Input
-                                    id="tagName"
-                                    value={newTagName}
-                                    onChange={(e) => setNewTagName(e.target.value)}
-                                    placeholder="Enter tag name"
-                                />
-                            </div>
-                            <div className="space-y-2">
-                                <Label htmlFor="tagColor">Color</Label>
-                                <Input
-                                    type="color"
-                                    id="tagColor"
-                                    value={newTagColor}
-                                    onChange={(e) => setNewTagColor(e.target.value)}
-                                    className="h-10 w-full"
-                                />
-                            </div>
-                            {createTagMutation.isError && (
-                                <div className="text-sm text-red-500">
-                                    {createTagMutation.error instanceof Error
-                                        ? createTagMutation.error.message
-                                        : 'Failed to create tag'}
-                                </div>
-                            )}
-                            <Button
-                                type="submit"
-                                className="w-full"
-                                disabled={createTagMutation.isPending}
-                            >
-                                {createTagMutation.isPending ? 'Creating...' : 'Create Tag'}
+                    )}
+
+                    {/* Expand/Collapse Controls */}
+                    {groupedTags.length > 0 && (
+                        <>
+                            <Button variant="ghost" size="sm" onClick={expandAll}>
+                                Expand All
                             </Button>
-                        </form>
-                    </DialogContent>
-                </Dialog>
+                            <Button variant="ghost" size="sm" onClick={collapseAll}>
+                                Collapse All
+                            </Button>
+                        </>
+                    )}
+
+                    {/* Create Tag Dropdown */}
+                    <DropdownMenu>
+                        <DropdownMenuTrigger asChild>
+                            <Button>
+                                <Plus className="h-4 w-4 mr-2" />
+                                Create Tag
+                            </Button>
+                        </DropdownMenuTrigger>
+                        <DropdownMenuContent align="end">
+                            <DropdownMenuItem onClick={() => openCreateDialog('category')}>
+                                <FolderPlus className="h-4 w-4 mr-2" />
+                                Create Category
+                            </DropdownMenuItem>
+                            <DropdownMenuItem
+                                onClick={() => openCreateDialog('subcategory')}
+                                disabled={categories.length === 0}
+                            >
+                                <TagIcon className="h-4 w-4 mr-2" />
+                                Create Subcategory
+                            </DropdownMenuItem>
+                            {categories.length === 0 && (
+                                <p className="px-2 py-1 text-xs text-muted-foreground">
+                                    Create a category first
+                                </p>
+                            )}
+                        </DropdownMenuContent>
+                    </DropdownMenu>
+                </div>
             </div>
 
-            <div className="rounded-md border">
-                <Table>
-                    <TableHeader>
-                        <TableRow>
-                            <TableHead>Color</TableHead>
-                            <TableHead>Name</TableHead>
-                            <TableHead className="text-right">Actions</TableHead>
-                        </TableRow>
-                    </TableHeader>
-                    <TableBody>
-                        {tags.map(tag => (
-                            <TableRow key={tag.id}>
-                                <TableCell>
-                                    <div
-                                        className="w-6 h-6 rounded-full"
-                                        style={{ backgroundColor: tag.color || '#000000' }}
-                                    />
-                                </TableCell>
-                                <TableCell>{tag.name}</TableCell>
-                                <TableCell className="text-right">
-                                    <div className="flex justify-end gap-2">
-                                        <Dialog
-                                            open={editingTagId === tag.id}
-                                            onOpenChange={(open) => {
-                                                if (!open) {
-                                                    setEditingTagId(null)
-                                                    setEditingTag(null)
-                                                }
-                                            }}
-                                        >
-                                            <DialogTrigger asChild>
-                                                <Button
-                                                    variant="ghost"
-                                                    size="icon"
-                                                    onClick={() => {
-                                                        setEditingTag(tag)
-                                                        setEditingTagId(tag.id)
-                                                    }}
-                                                >
-                                                    <Pencil className="h-4 w-4" />
-                                                </Button>
-                                            </DialogTrigger>
-                                            <DialogContent className="bg-white">
-                                                <DialogHeader>
-                                                    <DialogTitle>Edit Tag</DialogTitle>
-                                                </DialogHeader>
-                                                {editingTag && (
-                                                    <form
-                                                        onSubmit={(e) => {
-                                                            e.preventDefault()
-                                                            handleUpdateTag(tag.id, editingTag)
-                                                        }}
-                                                        className="space-y-4"
+            {/* Create Tag Dialog */}
+            <Dialog open={isCreateDialogOpen} onOpenChange={closeDialogs}>
+                <DialogContent className="max-w-md">
+                    <DialogHeader>
+                        <DialogTitle>
+                            Create {formData.tagType === 'category' ? 'Category' : 'Subcategory'}
+                        </DialogTitle>
+                    </DialogHeader>
+                    <HierarchicalTagForm
+                        formData={formData}
+                        categories={categories}
+                        onFormDataChange={updateFormData}
+                        onSubmit={handleCreateSubmit}
+                        isSubmitting={isCreating}
+                        submitButtonText="Create Tag"
+                        error={createError}
+                        mode="create"
+                    />
+                </DialogContent>
+            </Dialog>
+
+            {/* Edit Tag Dialog */}
+            <Dialog open={isEditDialogOpen} onOpenChange={closeDialogs}>
+                <DialogContent className="max-w-md">
+                    <DialogHeader>
+                        <DialogTitle>
+                            Edit {editingTag?.tag_type === 'category' ? 'Category' : 'Subcategory'}
+                        </DialogTitle>
+                    </DialogHeader>
+                    <HierarchicalTagForm
+                        formData={formData}
+                        categories={categories}
+                        onFormDataChange={updateFormData}
+                        onSubmit={handleEditSubmit}
+                        isSubmitting={isUpdating}
+                        submitButtonText="Save Changes"
+                        error={updateError}
+                        mode="edit"
+                    />
+                </DialogContent>
+            </Dialog>
+
+            {/* Hierarchical Tags List */}
+            <div className="space-y-4">
+                {groupedTags.map(({ category, subcategories }) => {
+                    const isExpanded = expandedCategories.has(category.id)
+
+                    return (
+                        <div key={category.id} className="rounded-lg border bg-card">
+                            {/* Category Header */}
+                            <Collapsible open={isExpanded} onOpenChange={() => toggleCategory(category.id)}>
+                                <CollapsibleTrigger className="w-full">
+                                    <div className="flex items-center justify-between p-4 hover:bg-muted/50 transition-colors">
+                                        <div className="flex items-center space-x-3">
+                                            {isExpanded ? (
+                                                <ChevronDown className="h-4 w-4 text-muted-foreground" />
+                                            ) : (
+                                                <ChevronRight className="h-4 w-4 text-muted-foreground" />
+                                            )}
+                                            <div
+                                                className="w-4 h-4 rounded-full border"
+                                                style={{ backgroundColor: category.color || '#6B7280' }}
+                                            />
+                                            <div className="text-left">
+                                                <h3 className="font-semibold text-lg">{category.name}</h3>
+                                                <p className="text-sm text-muted-foreground">
+                                                    {subcategories.length} subcategories
+                                                    {category.is_system && (
+                                                        <span className="ml-2 text-xs bg-blue-100 text-blue-800 px-1.5 py-0.5 rounded">
+                                                            System
+                                                        </span>
+                                                    )}
+                                                </p>
+                                            </div>
+                                        </div>
+
+                                        <div className="flex items-center space-x-1" onClick={(e) => e.stopPropagation()}>
+                                            <Button
+                                                variant="ghost"
+                                                size="icon"
+                                                onClick={() => openEditDialog(category)}
+                                                disabled={isUpdating || isDeleting}
+                                            >
+                                                <Pencil className="h-4 w-4" />
+                                            </Button>
+
+                                            <AlertDialog>
+                                                <AlertDialogTrigger asChild>
+                                                    <Button
+                                                        variant="ghost"
+                                                        size="icon"
+                                                        disabled={isDeleting}
                                                     >
-                                                        <div className="space-y-2">
-                                                            <Label htmlFor="editTagName">Name</Label>
-                                                            <Input
-                                                                id="editTagName"
-                                                                value={editingTag.name}
-                                                                onChange={(e) =>
-                                                                    setEditingTag({ ...editingTag, name: e.target.value })
-                                                                }
-                                                                placeholder="Enter tag name"
-                                                            />
-                                                        </div>
-                                                        <div className="space-y-2">
-                                                            <Label htmlFor="editTagColor">Color</Label>
-                                                            <Input
-                                                                type="color"
-                                                                id="editTagColor"
-                                                                value={editingTag.color || '#000000'}
-                                                                onChange={(e) =>
-                                                                    setEditingTag({ ...editingTag, color: e.target.value })
-                                                                }
-                                                                className="h-10 w-full"
-                                                            />
-                                                        </div>
-                                                        <Button
-                                                            type="submit"
-                                                            className="w-full"
-                                                            disabled={updateTagMutation.isPending}
+                                                        <Trash2 className="h-4 w-4" />
+                                                    </Button>
+                                                </AlertDialogTrigger>
+                                                <AlertDialogContent>
+                                                    <AlertDialogHeader>
+                                                        <AlertDialogTitle>Delete Category</AlertDialogTitle>
+                                                        <AlertDialogDescription>
+                                                            Are you sure you want to delete "{category.name}"?
+                                                            <span className="block mt-2 text-destructive">
+                                                                This will also delete all {subcategories.length} subcategories within this category.
+                                                            </span>
+                                                            This action cannot be undone.
+                                                        </AlertDialogDescription>
+                                                    </AlertDialogHeader>
+                                                    <AlertDialogFooter>
+                                                        <AlertDialogCancel>Cancel</AlertDialogCancel>
+                                                        <AlertDialogAction
+                                                            onClick={() => handleDelete(category.id)}
+                                                            className="bg-destructive text-destructive-foreground hover:bg-destructive/90"
                                                         >
-                                                            {updateTagMutation.isPending ? 'Saving...' : 'Save Changes'}
-                                                        </Button>
-                                                    </form>
-                                                )}
-                                            </DialogContent>
-                                        </Dialog>
-                                        <AlertDialog>
-                                            <AlertDialogTrigger asChild>
-                                                <Button variant="ghost" size="icon">
-                                                    <Trash2 className="h-4 w-4" />
-                                                </Button>
-                                            </AlertDialogTrigger>
-                                            <AlertDialogContent>
-                                                <AlertDialogHeader>
-                                                    <AlertDialogTitle>Are you sure?</AlertDialogTitle>
-                                                    <AlertDialogDescription>
-                                                        This action cannot be undone. This will permanently delete the tag.
-                                                    </AlertDialogDescription>
-                                                </AlertDialogHeader>
-                                                <AlertDialogFooter>
-                                                    <AlertDialogCancel>Cancel</AlertDialogCancel>
-                                                    <AlertDialogAction onClick={() => deleteTagMutation.mutate(tag.id)}>
-                                                        Delete
-                                                    </AlertDialogAction>
-                                                </AlertDialogFooter>
-                                            </AlertDialogContent>
-                                        </AlertDialog>
+                                                            Delete Category
+                                                        </AlertDialogAction>
+                                                    </AlertDialogFooter>
+                                                </AlertDialogContent>
+                                            </AlertDialog>
+                                        </div>
                                     </div>
-                                </TableCell>
-                            </TableRow>
-                        ))}
-                    </TableBody>
-                </Table>
+                                </CollapsibleTrigger>
+
+                                {/* Subcategories */}
+                                <CollapsibleContent>
+                                    {subcategories.length > 0 ? (
+                                        <div className="border-t bg-muted/20">
+                                            <Table>
+                                                <TableHeader>
+                                                    <TableRow>
+                                                        <TableHead className="w-12"></TableHead>
+                                                        <TableHead>Name</TableHead>
+                                                        <TableHead className="w-20">Order</TableHead>
+                                                        <TableHead className="w-24 text-right">Actions</TableHead>
+                                                    </TableRow>
+                                                </TableHeader>
+                                                <TableBody>
+                                                    {subcategories.map(subcategory => (
+                                                        <TableRow key={subcategory.id}>
+                                                            <TableCell>
+                                                                <div
+                                                                    className="w-4 h-4 rounded-full border mx-auto"
+                                                                    style={{ backgroundColor: subcategory.color || '#6B7280' }}
+                                                                />
+                                                            </TableCell>
+                                                            <TableCell>
+                                                                <div className="flex items-center">
+                                                                    <span className={subcategory.is_system ? 'font-medium' : ''}>
+                                                                        {subcategory.name}
+                                                                    </span>
+                                                                    {subcategory.is_system && (
+                                                                        <span className="ml-2 text-xs bg-blue-100 text-blue-800 px-1.5 py-0.5 rounded">
+                                                                            System
+                                                                        </span>
+                                                                    )}
+                                                                </div>
+                                                            </TableCell>
+                                                            <TableCell>
+                                                                <span className="text-sm text-muted-foreground">
+                                                                    {subcategory.sort_order || 0}
+                                                                </span>
+                                                            </TableCell>
+                                                            <TableCell className="text-right">
+                                                                <div className="flex justify-end gap-1">
+                                                                    <Button
+                                                                        variant="ghost"
+                                                                        size="icon"
+                                                                        onClick={() => openEditDialog(subcategory)}
+                                                                        disabled={isUpdating || isDeleting}
+                                                                    >
+                                                                        <Pencil className="h-4 w-4" />
+                                                                    </Button>
+
+                                                                    <AlertDialog>
+                                                                        <AlertDialogTrigger asChild>
+                                                                            <Button
+                                                                                variant="ghost"
+                                                                                size="icon"
+                                                                                disabled={isDeleting}
+                                                                            >
+                                                                                <Trash2 className="h-4 w-4" />
+                                                                            </Button>
+                                                                        </AlertDialogTrigger>
+                                                                        <AlertDialogContent>
+                                                                            <AlertDialogHeader>
+                                                                                <AlertDialogTitle>Delete Subcategory</AlertDialogTitle>
+                                                                                <AlertDialogDescription>
+                                                                                    Are you sure you want to delete "{subcategory.name}"?
+                                                                                    This action cannot be undone.
+                                                                                </AlertDialogDescription>
+                                                                            </AlertDialogHeader>
+                                                                            <AlertDialogFooter>
+                                                                                <AlertDialogCancel>Cancel</AlertDialogCancel>
+                                                                                <AlertDialogAction
+                                                                                    onClick={() => handleDelete(subcategory.id)}
+                                                                                    className="bg-destructive text-destructive-foreground hover:bg-destructive/90"
+                                                                                >
+                                                                                    Delete
+                                                                                </AlertDialogAction>
+                                                                            </AlertDialogFooter>
+                                                                        </AlertDialogContent>
+                                                                    </AlertDialog>
+                                                                </div>
+                                                            </TableCell>
+                                                        </TableRow>
+                                                    ))}
+                                                </TableBody>
+                                            </Table>
+                                        </div>
+                                    ) : (
+                                        <div className="p-8 text-center text-muted-foreground border-t bg-muted/10">
+                                            <p>No subcategories in this category</p>
+                                            <Button
+                                                variant="outline"
+                                                size="sm"
+                                                className="mt-2"
+                                                onClick={() => openCreateDialog('subcategory', category.id)}
+                                            >
+                                                <Plus className="h-3 w-3 mr-1" />
+                                                Add Subcategory
+                                            </Button>
+                                        </div>
+                                    )}
+                                </CollapsibleContent>
+                            </Collapsible>
+                        </div>
+                    )
+                })}
             </div>
+
+            {tags.length === 0 && (
+                <div className="text-center py-12 text-muted-foreground">
+                    <p className="text-lg mb-2">No tags created yet</p>
+                    <p className="mb-4">Create your first tag or seed with predefined issue types</p>
+                </div>
+            )}
         </div>
     )
 }
diff --git a/src/types/database.types.ts b/src/types/database.types.ts
index 32776b2..1965940 100644
--- a/src/types/database.types.ts
+++ b/src/types/database.types.ts
@@ -4,411 +4,430 @@ export type Json =
   | boolean
   | null
   | { [key: string]: Json | undefined }
-  | Json[]
+  | Json[];
 
 export type Database = {
   graphql_public: {
     Tables: {
-      [_ in never]: never
-    }
+      [_ in never]: never;
+    };
     Views: {
-      [_ in never]: never
-    }
+      [_ in never]: never;
+    };
     Functions: {
       graphql: {
         Args: {
-          operationName?: string
-          query?: string
-          variables?: Json
-          extensions?: Json
-        }
-        Returns: Json
-      }
-    }
+          operationName?: string;
+          query?: string;
+          variables?: Json;
+          extensions?: Json;
+        };
+        Returns: Json;
+      };
+    };
     Enums: {
-      [_ in never]: never
-    }
+      [_ in never]: never;
+    };
     CompositeTypes: {
-      [_ in never]: never
-    }
-  }
+      [_ in never]: never;
+    };
+  };
   public: {
     Tables: {
       profiles: {
         Row: {
-          avatar_url: string | null
-          created_at: string | null
-          full_name: string | null
-          github_id: number | null
-          github_username: string | null
-          id: string
-        }
+          avatar_url: string | null;
+          created_at: string | null;
+          full_name: string | null;
+          github_id: number | null;
+          github_username: string | null;
+          id: string;
+        };
         Insert: {
-          avatar_url?: string | null
-          created_at?: string | null
-          full_name?: string | null
-          github_id?: number | null
-          github_username?: string | null
-          id: string
-        }
+          avatar_url?: string | null;
+          created_at?: string | null;
+          full_name?: string | null;
+          github_id?: number | null;
+          github_username?: string | null;
+          id: string;
+        };
         Update: {
-          avatar_url?: string | null
-          created_at?: string | null
-          full_name?: string | null
-          github_id?: number | null
-          github_username?: string | null
-          id?: string
-        }
-        Relationships: []
-      }
+          avatar_url?: string | null;
+          created_at?: string | null;
+          full_name?: string | null;
+          github_id?: number | null;
+          github_username?: string | null;
+          id?: string;
+        };
+        Relationships: [];
+      };
       session_tags: {
         Row: {
-          session_id: string
-          tag_id: string
-        }
+          session_id: string;
+          tag_id: string;
+        };
         Insert: {
-          session_id: string
-          tag_id: string
-        }
+          session_id: string;
+          tag_id: string;
+        };
         Update: {
-          session_id?: string
-          tag_id?: string
-        }
+          session_id?: string;
+          tag_id?: string;
+        };
         Relationships: [
           {
-            foreignKeyName: "session_tags_session_id_fkey"
-            columns: ["session_id"]
-            isOneToOne: false
-            referencedRelation: "sessions"
-            referencedColumns: ["id"]
+            foreignKeyName: "session_tags_session_id_fkey";
+            columns: ["session_id"];
+            isOneToOne: false;
+            referencedRelation: "sessions";
+            referencedColumns: ["id"];
           },
           {
-            foreignKeyName: "session_tags_tag_id_fkey"
-            columns: ["tag_id"]
-            isOneToOne: false
-            referencedRelation: "tags"
-            referencedColumns: ["id"]
-          },
-        ]
-      }
+            foreignKeyName: "session_tags_tag_id_fkey";
+            columns: ["tag_id"];
+            isOneToOne: false;
+            referencedRelation: "tags";
+            referencedColumns: ["id"];
+          }
+        ];
+      };
       sessions: {
         Row: {
-          comment_url: string | null
-          ended_at: string | null
-          id: string
-          skipped_summary: boolean | null
-          space_member_id: string | null
-          started_at: string
-          track_id: string | null
-        }
+          comment_url: string | null;
+          ended_at: string | null;
+          id: string;
+          skipped_summary: boolean | null;
+          space_member_id: string | null;
+          started_at: string;
+          track_id: string | null;
+        };
         Insert: {
-          comment_url?: string | null
-          ended_at?: string | null
-          id?: string
-          skipped_summary?: boolean | null
-          space_member_id?: string | null
-          started_at: string
-          track_id?: string | null
-        }
+          comment_url?: string | null;
+          ended_at?: string | null;
+          id?: string;
+          skipped_summary?: boolean | null;
+          space_member_id?: string | null;
+          started_at: string;
+          track_id?: string | null;
+        };
         Update: {
-          comment_url?: string | null
-          ended_at?: string | null
-          id?: string
-          skipped_summary?: boolean | null
-          space_member_id?: string | null
-          started_at?: string
-          track_id?: string | null
-        }
+          comment_url?: string | null;
+          ended_at?: string | null;
+          id?: string;
+          skipped_summary?: boolean | null;
+          space_member_id?: string | null;
+          started_at?: string;
+          track_id?: string | null;
+        };
         Relationships: [
           {
-            foreignKeyName: "sessions_space_member_id_fkey"
-            columns: ["space_member_id"]
-            isOneToOne: false
-            referencedRelation: "space_members"
-            referencedColumns: ["id"]
+            foreignKeyName: "sessions_space_member_id_fkey";
+            columns: ["space_member_id"];
+            isOneToOne: false;
+            referencedRelation: "space_members";
+            referencedColumns: ["id"];
           },
           {
-            foreignKeyName: "sessions_track_id_fkey"
-            columns: ["track_id"]
-            isOneToOne: false
-            referencedRelation: "tracks"
-            referencedColumns: ["id"]
-          },
-        ]
-      }
+            foreignKeyName: "sessions_track_id_fkey";
+            columns: ["track_id"];
+            isOneToOne: false;
+            referencedRelation: "tracks";
+            referencedColumns: ["id"];
+          }
+        ];
+      };
       space_members: {
         Row: {
-          id: string
-          joined_at: string | null
-          last_active_at: string | null
-          last_status_update_at: string | null
-          location: string | null
-          nickname: string | null
-          role: string
-          space_id: string | null
-          status: string | null
-          user_id: string | null
-        }
+          id: string;
+          joined_at: string | null;
+          last_active_at: string | null;
+          last_status_update_at: string | null;
+          location: string | null;
+          nickname: string | null;
+          role: string;
+          space_id: string | null;
+          status: string | null;
+          user_id: string | null;
+        };
         Insert: {
-          id?: string
-          joined_at?: string | null
-          last_active_at?: string | null
-          last_status_update_at?: string | null
-          location?: string | null
-          nickname?: string | null
-          role: string
-          space_id?: string | null
-          status?: string | null
-          user_id?: string | null
-        }
+          id?: string;
+          joined_at?: string | null;
+          last_active_at?: string | null;
+          last_status_update_at?: string | null;
+          location?: string | null;
+          nickname?: string | null;
+          role: string;
+          space_id?: string | null;
+          status?: string | null;
+          user_id?: string | null;
+        };
         Update: {
-          id?: string
-          joined_at?: string | null
-          last_active_at?: string | null
-          last_status_update_at?: string | null
-          location?: string | null
-          nickname?: string | null
-          role?: string
-          space_id?: string | null
-          status?: string | null
-          user_id?: string | null
-        }
+          id?: string;
+          joined_at?: string | null;
+          last_active_at?: string | null;
+          last_status_update_at?: string | null;
+          location?: string | null;
+          nickname?: string | null;
+          role?: string;
+          space_id?: string | null;
+          status?: string | null;
+          user_id?: string | null;
+        };
         Relationships: [
           {
-            foreignKeyName: "space_members_space_id_fkey"
-            columns: ["space_id"]
-            isOneToOne: false
-            referencedRelation: "spaces"
-            referencedColumns: ["id"]
-          },
-        ]
-      }
+            foreignKeyName: "space_members_space_id_fkey";
+            columns: ["space_id"];
+            isOneToOne: false;
+            referencedRelation: "spaces";
+            referencedColumns: ["id"];
+          }
+        ];
+      };
       spaces: {
         Row: {
-          avatar_url: string | null
-          created_at: string | null
-          github_org_id: number | null
-          id: string
-          name: string
-          plan: string | null
-          slug: string
-          updated_at: string | null
-        }
+          avatar_url: string | null;
+          created_at: string | null;
+          github_org_id: number | null;
+          id: string;
+          name: string;
+          plan: string | null;
+          slug: string;
+          updated_at: string | null;
+        };
         Insert: {
-          avatar_url?: string | null
-          created_at?: string | null
-          github_org_id?: number | null
-          id?: string
-          name: string
-          plan?: string | null
-          slug: string
-          updated_at?: string | null
-        }
+          avatar_url?: string | null;
+          created_at?: string | null;
+          github_org_id?: number | null;
+          id?: string;
+          name: string;
+          plan?: string | null;
+          slug: string;
+          updated_at?: string | null;
+        };
         Update: {
-          avatar_url?: string | null
-          created_at?: string | null
-          github_org_id?: number | null
-          id?: string
-          name?: string
-          plan?: string | null
-          slug?: string
-          updated_at?: string | null
-        }
-        Relationships: []
-      }
+          avatar_url?: string | null;
+          created_at?: string | null;
+          github_org_id?: number | null;
+          id?: string;
+          name?: string;
+          plan?: string | null;
+          slug?: string;
+          updated_at?: string | null;
+        };
+        Relationships: [];
+      };
       tags: {
         Row: {
-          color: string | null
-          created_at: string | null
-          id: string
-          name: string
-          space_id: string | null
-        }
+          color: string | null;
+          created_at: string | null;
+          id: string;
+          is_system: boolean | null;
+          name: string;
+          parent_id: string | null;
+          sort_order: number | null;
+          space_id: string | null;
+          tag_type: string | null;
+        };
         Insert: {
-          color?: string | null
-          created_at?: string | null
-          id?: string
-          name: string
-          space_id?: string | null
-        }
+          color?: string | null;
+          created_at?: string | null;
+          id?: string;
+          is_system?: boolean | null;
+          name: string;
+          parent_id?: string | null;
+          sort_order?: number | null;
+          space_id?: string | null;
+          tag_type?: string | null;
+        };
         Update: {
-          color?: string | null
-          created_at?: string | null
-          id?: string
-          name?: string
-          space_id?: string | null
-        }
+          color?: string | null;
+          created_at?: string | null;
+          id?: string;
+          is_system?: boolean | null;
+          name?: string;
+          parent_id?: string | null;
+          sort_order?: number | null;
+          space_id?: string | null;
+          tag_type?: string | null;
+        };
         Relationships: [
           {
-            foreignKeyName: "tags_space_id_fkey"
-            columns: ["space_id"]
-            isOneToOne: false
-            referencedRelation: "spaces"
-            referencedColumns: ["id"]
+            foreignKeyName: "tags_parent_id_fkey";
+            columns: ["parent_id"];
+            isOneToOne: false;
+            referencedRelation: "tags";
+            referencedColumns: ["id"];
           },
-        ]
-      }
+          {
+            foreignKeyName: "tags_space_id_fkey";
+            columns: ["space_id"];
+            isOneToOne: false;
+            referencedRelation: "spaces";
+            referencedColumns: ["id"];
+          }
+        ];
+      };
       tracks: {
         Row: {
-          created_at: string | null
-          created_by: string | null
-          id: string
-          issue_number: number
-          repo_name: string
-          repo_owner: string
-          space_id: string | null
-          title: string | null
-        }
+          created_at: string | null;
+          created_by: string | null;
+          id: string;
+          issue_number: number;
+          repo_name: string;
+          repo_owner: string;
+          space_id: string | null;
+          title: string | null;
+        };
         Insert: {
-          created_at?: string | null
-          created_by?: string | null
-          id?: string
-          issue_number: number
-          repo_name: string
-          repo_owner: string
-          space_id?: string | null
-          title?: string | null
-        }
+          created_at?: string | null;
+          created_by?: string | null;
+          id?: string;
+          issue_number: number;
+          repo_name: string;
+          repo_owner: string;
+          space_id?: string | null;
+          title?: string | null;
+        };
         Update: {
-          created_at?: string | null
-          created_by?: string | null
-          id?: string
-          issue_number?: number
-          repo_name?: string
-          repo_owner?: string
-          space_id?: string | null
-          title?: string | null
-        }
+          created_at?: string | null;
+          created_by?: string | null;
+          id?: string;
+          issue_number?: number;
+          repo_name?: string;
+          repo_owner?: string;
+          space_id?: string | null;
+          title?: string | null;
+        };
         Relationships: [
           {
-            foreignKeyName: "tracks_space_id_fkey"
-            columns: ["space_id"]
-            isOneToOne: false
-            referencedRelation: "spaces"
-            referencedColumns: ["id"]
-          },
-        ]
-      }
-    }
+            foreignKeyName: "tracks_space_id_fkey";
+            columns: ["space_id"];
+            isOneToOne: false;
+            referencedRelation: "spaces";
+            referencedColumns: ["id"];
+          }
+        ];
+      };
+    };
     Views: {
-      [_ in never]: never
-    }
+      [_ in never]: never;
+    };
     Functions: {
-      [_ in never]: never
-    }
+      [_ in never]: never;
+    };
     Enums: {
-      [_ in never]: never
-    }
+      [_ in never]: never;
+    };
     CompositeTypes: {
-      [_ in never]: never
-    }
-  }
-}
+      [_ in never]: never;
+    };
+  };
+};
 
-type DefaultSchema = Database[Extract<keyof Database, "public">]
+type DefaultSchema = Database[Extract<keyof Database, "public">];
 
 export type Tables<
   DefaultSchemaTableNameOrOptions extends
     | keyof (DefaultSchema["Tables"] & DefaultSchema["Views"])
     | { schema: keyof Database },
   TableName extends DefaultSchemaTableNameOrOptions extends {
-    schema: keyof Database
+    schema: keyof Database;
   }
     ? keyof (Database[DefaultSchemaTableNameOrOptions["schema"]]["Tables"] &
         Database[DefaultSchemaTableNameOrOptions["schema"]]["Views"])
-    : never = never,
+    : never = never
 > = DefaultSchemaTableNameOrOptions extends { schema: keyof Database }
   ? (Database[DefaultSchemaTableNameOrOptions["schema"]]["Tables"] &
       Database[DefaultSchemaTableNameOrOptions["schema"]]["Views"])[TableName] extends {
-      Row: infer R
+      Row: infer R;
     }
     ? R
     : never
   : DefaultSchemaTableNameOrOptions extends keyof (DefaultSchema["Tables"] &
-        DefaultSchema["Views"])
-    ? (DefaultSchema["Tables"] &
-        DefaultSchema["Views"])[DefaultSchemaTableNameOrOptions] extends {
-        Row: infer R
-      }
-      ? R
-      : never
+      DefaultSchema["Views"])
+  ? (DefaultSchema["Tables"] &
+      DefaultSchema["Views"])[DefaultSchemaTableNameOrOptions] extends {
+      Row: infer R;
+    }
+    ? R
     : never
+  : never;
 
 export type TablesInsert<
   DefaultSchemaTableNameOrOptions extends
     | keyof DefaultSchema["Tables"]
     | { schema: keyof Database },
   TableName extends DefaultSchemaTableNameOrOptions extends {
-    schema: keyof Database
+    schema: keyof Database;
   }
     ? keyof Database[DefaultSchemaTableNameOrOptions["schema"]]["Tables"]
-    : never = never,
+    : never = never
 > = DefaultSchemaTableNameOrOptions extends { schema: keyof Database }
   ? Database[DefaultSchemaTableNameOrOptions["schema"]]["Tables"][TableName] extends {
-      Insert: infer I
+      Insert: infer I;
     }
     ? I
     : never
   : DefaultSchemaTableNameOrOptions extends keyof DefaultSchema["Tables"]
-    ? DefaultSchema["Tables"][DefaultSchemaTableNameOrOptions] extends {
-        Insert: infer I
-      }
-      ? I
-      : never
+  ? DefaultSchema["Tables"][DefaultSchemaTableNameOrOptions] extends {
+      Insert: infer I;
+    }
+    ? I
     : never
+  : never;
 
 export type TablesUpdate<
   DefaultSchemaTableNameOrOptions extends
     | keyof DefaultSchema["Tables"]
     | { schema: keyof Database },
   TableName extends DefaultSchemaTableNameOrOptions extends {
-    schema: keyof Database
+    schema: keyof Database;
   }
     ? keyof Database[DefaultSchemaTableNameOrOptions["schema"]]["Tables"]
-    : never = never,
+    : never = never
 > = DefaultSchemaTableNameOrOptions extends { schema: keyof Database }
   ? Database[DefaultSchemaTableNameOrOptions["schema"]]["Tables"][TableName] extends {
-      Update: infer U
+      Update: infer U;
     }
     ? U
     : never
   : DefaultSchemaTableNameOrOptions extends keyof DefaultSchema["Tables"]
-    ? DefaultSchema["Tables"][DefaultSchemaTableNameOrOptions] extends {
-        Update: infer U
-      }
-      ? U
-      : never
+  ? DefaultSchema["Tables"][DefaultSchemaTableNameOrOptions] extends {
+      Update: infer U;
+    }
+    ? U
     : never
+  : never;
 
 export type Enums<
   DefaultSchemaEnumNameOrOptions extends
     | keyof DefaultSchema["Enums"]
     | { schema: keyof Database },
   EnumName extends DefaultSchemaEnumNameOrOptions extends {
-    schema: keyof Database
+    schema: keyof Database;
   }
     ? keyof Database[DefaultSchemaEnumNameOrOptions["schema"]]["Enums"]
-    : never = never,
+    : never = never
 > = DefaultSchemaEnumNameOrOptions extends { schema: keyof Database }
   ? Database[DefaultSchemaEnumNameOrOptions["schema"]]["Enums"][EnumName]
   : DefaultSchemaEnumNameOrOptions extends keyof DefaultSchema["Enums"]
-    ? DefaultSchema["Enums"][DefaultSchemaEnumNameOrOptions]
-    : never
+  ? DefaultSchema["Enums"][DefaultSchemaEnumNameOrOptions]
+  : never;
 
 export type CompositeTypes<
   PublicCompositeTypeNameOrOptions extends
     | keyof DefaultSchema["CompositeTypes"]
     | { schema: keyof Database },
   CompositeTypeName extends PublicCompositeTypeNameOrOptions extends {
-    schema: keyof Database
+    schema: keyof Database;
   }
     ? keyof Database[PublicCompositeTypeNameOrOptions["schema"]]["CompositeTypes"]
-    : never = never,
+    : never = never
 > = PublicCompositeTypeNameOrOptions extends { schema: keyof Database }
   ? Database[PublicCompositeTypeNameOrOptions["schema"]]["CompositeTypes"][CompositeTypeName]
   : PublicCompositeTypeNameOrOptions extends keyof DefaultSchema["CompositeTypes"]
-    ? DefaultSchema["CompositeTypes"][PublicCompositeTypeNameOrOptions]
-    : never
+  ? DefaultSchema["CompositeTypes"][PublicCompositeTypeNameOrOptions]
+  : never;
 
 export const Constants = {
   graphql_public: {
@@ -417,5 +436,4 @@ export const Constants = {
   public: {
     Enums: {},
   },
-} as const
-
+} as const;
diff --git a/src/types/index.ts b/src/types/index.ts
index 40429e4..6460a4d 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -13,6 +13,19 @@ export type Session = Database["public"]["Tables"]["sessions"]["Row"];
 
 export type Tag = Database["public"]["Tables"]["tags"]["Row"];
 
+// Extended tag types for hierarchical structure
+export interface HierarchicalTag extends Tag {
+  children?: Tag[];
+  parent?: Tag;
+}
+
+export type TagType = "category" | "subcategory";
+
+export interface TagWithRelations extends Tag {
+  children?: Tag[];
+  parent?: Tag;
+}
+
 // This interface extends the Space interface to include membership information
 export interface SpaceWithMembership extends Space {
   is_member: boolean;
diff --git a/supabase/migrations/20250719004549_add_hierarchy_to_tags.sql b/supabase/migrations/20250719004549_add_hierarchy_to_tags.sql
new file mode 100644
index 0000000..7d1f935
--- /dev/null
+++ b/supabase/migrations/20250719004549_add_hierarchy_to_tags.sql
@@ -0,0 +1,15 @@
+-- Add hierarchy fields to tags table
+ALTER TABLE tags 
+ADD COLUMN parent_id UUID REFERENCES tags(id) ON DELETE CASCADE,
+ADD COLUMN tag_type TEXT CHECK (tag_type IN ('category', 'subcategory')) DEFAULT 'subcategory',
+ADD COLUMN sort_order INTEGER DEFAULT 0,
+ADD COLUMN is_system BOOLEAN DEFAULT false;
+
+-- Add indexes for performance
+CREATE INDEX idx_tags_parent_id ON tags(parent_id);
+CREATE INDEX idx_tags_tag_type ON tags(tag_type);
+CREATE INDEX idx_tags_sort_order ON tags(sort_order);
+CREATE INDEX idx_tags_is_system ON tags(is_system);
+
+-- Update existing tags to be subcategories (backward compatibility)
+UPDATE tags SET tag_type = 'subcategory' WHERE tag_type IS NULL;

From 87804b5a04b4bd561565af25094f9200e363ea5e Mon Sep 17 00:00:00 2001
From: Mina Sameh <mina.sameh.lameh@gmail.com>
Date: Sat, 19 Jul 2025 04:26:41 +0300
Subject: [PATCH 3/3] refactor: remove unused mode prop from
 HierarchicalTagForm and clean up related components

- Removed the mode prop from HierarchicalTagFormProps and its usage in the component.
- Updated TagsPage to eliminate mode prop from tag creation and editing dialogs.
- Cleaned up imports in use-tags and mutations files by removing unused functions and simplifying loops.
---
 src/components/hierarchical-tag-form.tsx | 2 --
 src/hooks/api/use-tags.ts                | 2 +-
 src/lib/supabase/mutations.ts            | 4 +---
 src/routes/space/$slug/tags/index.tsx    | 2 --
 4 files changed, 2 insertions(+), 8 deletions(-)

diff --git a/src/components/hierarchical-tag-form.tsx b/src/components/hierarchical-tag-form.tsx
index 4af1c22..39af7d5 100644
--- a/src/components/hierarchical-tag-form.tsx
+++ b/src/components/hierarchical-tag-form.tsx
@@ -24,7 +24,6 @@ interface HierarchicalTagFormProps {
     isSubmitting: boolean;
     submitButtonText: string;
     error?: Error | null;
-    mode: "create" | "edit";
 }
 
 export function HierarchicalTagForm({
@@ -35,7 +34,6 @@ export function HierarchicalTagForm({
     isSubmitting,
     submitButtonText,
     error,
-    mode,
 }: HierarchicalTagFormProps) {
     const isCategory = formData.tagType === "category";
     const requiresParent = formData.tagType === "subcategory";
diff --git a/src/hooks/api/use-tags.ts b/src/hooks/api/use-tags.ts
index b72e347..ebc2c12 100644
--- a/src/hooks/api/use-tags.ts
+++ b/src/hooks/api/use-tags.ts
@@ -1,6 +1,6 @@
 import { useState } from "react";
 import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
-import { getTags, getHierarchicalTags } from "@/lib/supabase/queries";
+import { getTags } from "@/lib/supabase/queries";
 import {
   createTag,
   deleteTag,
diff --git a/src/lib/supabase/mutations.ts b/src/lib/supabase/mutations.ts
index 7e59978..f864107 100644
--- a/src/lib/supabase/mutations.ts
+++ b/src/lib/supabase/mutations.ts
@@ -302,9 +302,7 @@ export async function seedIssueTypes(spaceId: string) {
 
   // Create categories first
   let categoryOrder = 0;
-  for (const [categoryName, categoryData] of Object.entries(
-    ISSUE_TYPE_HIERARCHY
-  )) {
+  for (const categoryData of Object.values(ISSUE_TYPE_HIERARCHY)) {
     const category = await createCategoryTag(
       spaceId,
       categoryData.name,
diff --git a/src/routes/space/$slug/tags/index.tsx b/src/routes/space/$slug/tags/index.tsx
index b71af42..b9dec9f 100644
--- a/src/routes/space/$slug/tags/index.tsx
+++ b/src/routes/space/$slug/tags/index.tsx
@@ -194,7 +194,6 @@ function TagsPage() {
                         isSubmitting={isCreating}
                         submitButtonText="Create Tag"
                         error={createError}
-                        mode="create"
                     />
                 </DialogContent>
             </Dialog>
@@ -215,7 +214,6 @@ function TagsPage() {
                         isSubmitting={isUpdating}
                         submitButtonText="Save Changes"
                         error={updateError}
-                        mode="edit"
                     />
                 </DialogContent>
             </Dialog>