@sociallane/elements 1.0.0

package/assets/js/utilities/split-text.js

@@ -0,0 +1,93 @@
+/**
+ * Split text animation utility.
+ * Text elements with data-sl-split animate characters/words/lines on scroll.
+ * Uses GSAP SplitText with masking for clean reveal effects.
+ *
+ * @package SocialLane_Elements
+ */
+
+import gsap from 'gsap';
+import { ScrollTrigger } from 'gsap/ScrollTrigger';
+import SplitText from 'gsap/SplitText';
+
+const splitInstances = new WeakMap();
+
+/**
+ * Initialize split text animations within a scope.
+ * Uses masked reveal effect for smooth clip-path animations.
+ *
+ * @param {Element|Document} scope Root element or document to search.
+ */
+export function initSplitText(scope = document) {
+  const container = scope instanceof Document ? scope.body : scope;
+  const els = container.querySelectorAll('[data-sl-split]');
+
+  els.forEach((el) => {
+    const type = el.getAttribute('data-sl-split') || 'lines';
+    const staggerVal = parseFloat(el.getAttribute('data-sl-split-stagger') || 0.03);
+    const duration = parseFloat(el.getAttribute('data-sl-split-duration') || 0.8);
+
+    if (!el.textContent.trim()) return;
+
+    // Determine split type and mask type
+    const typeMap = { chars: 'chars', words: 'words', lines: 'lines' };
+    const splitType = typeMap[type] || 'lines';
+
+    // Use SplitText.create() with masking for reveal effects (v3.13.0+)
+    const split = SplitText.create(el, {
+      type: splitType === 'chars' ? 'words, chars' : splitType === 'words' ? 'words' : 'lines',
+      mask: splitType, // Creates clipping wrapper for reveal effect
+      linesClass: 'sl-split-line',
+      wordsClass: 'sl-split-word',
+      charsClass: 'sl-split-char',
+      autoSplit: true,
+      onSplit(self) {
+        // Get the targets based on split type
+        const targets = self[splitType] ?? self.lines ?? self.words ?? self.chars;
+        if (!targets || targets.length === 0) return;
+
+        // Create masked reveal animation
+        // Elements start translated down and animate up into view (reveal through mask)
+        const tl = gsap.timeline({
+          scrollTrigger: {
+            trigger: el,
+            start: 'top 85%',
+            toggleActions: 'play none none none',
+          },
+        });
+
+        tl.fromTo(
+          targets,
+          {
+            yPercent: 100, // Start fully below the mask
+            opacity: 0,
+          },
+          {
+            yPercent: 0,
+            opacity: 1,
+            duration: duration,
+            stagger: staggerVal,
+            ease: 'power3.out',
+          }
+        );
+
+        return tl;
+      },
+    });
+
+    splitInstances.set(el, split);
+  });
+}
+
+/**
+ * Revert split text and clean up.
+ *
+ * @param {Element} el Element that was split.
+ */
+export function revertSplitText(el) {
+  const split = splitInstances.get(el);
+  if (split && typeof split.revert === 'function') {
+    split.revert();
+    splitInstances.delete(el);
+  }
+}

package/assets/js/utilities/stagger.js

@@ -0,0 +1,48 @@
+/**
+ * Stagger animation utility.
+ * Children of elements with data-sl-stagger animate in sequence.
+ * Uses smooth power3 easing for elegant reveal effects.
+ *
+ * @package SocialLane_Elements
+ */
+
+import gsap from 'gsap';
+import { ScrollTrigger } from 'gsap/ScrollTrigger';
+
+/**
+ * Initialize stagger animations within a scope.
+ *
+ * @param {Element|Document} scope Root element or document to search.
+ */
+export function initStagger(scope = document) {
+  const container = scope instanceof Document ? scope.body : scope;
+  const parents = container.querySelectorAll('[data-sl-stagger]');
+
+  parents.forEach((parent) => {
+    const delayStr = parent.getAttribute('data-sl-stagger');
+    const staggerDelay = delayStr ? parseFloat(delayStr) : 0.08;
+    const duration = parseFloat(parent.getAttribute('data-sl-stagger-duration') || 0.7);
+    const children = Array.from(parent.children).filter(
+      (c) => !c.hasAttribute('data-sl-stagger-skip')
+    );
+
+    if (children.length === 0) return;
+
+    gsap.fromTo(
+      children,
+      { opacity: 0, yPercent: 30 },
+      {
+        opacity: 1,
+        yPercent: 0,
+        duration: duration,
+        stagger: staggerDelay,
+        ease: 'power3.out',
+        scrollTrigger: {
+          trigger: parent,
+          start: 'top 85%',
+          toggleActions: 'play none none none',
+        },
+      }
+    );
+  });
+}

package/assets/previews/.gitkeep

@@ -0,0 +1,2 @@
+# Widget screenshot previews (e.g. hero-split.webp) go here.
+# See .cursor/skills/plugin-onboarding/SKILL.md for format and dimensions.

package/assets/previews/README.md

@@ -0,0 +1,65 @@
+# Widget screenshot previews
+
+We agreed on **screenshot previews** for the onboarding/settings widget browser so users can see what each widget looks like before enabling it.
+
+The app uses these images when they exist; until then it falls back to SVG icons.
+
+## Spec
+
+| Property   | Value |
+|-----------|--------|
+| **Format** | WebP |
+| **Dimensions** | 800×450 px (16:9) |
+| **Naming** | `{widget-slug}.webp` (must match slug exactly) |
+| **Location** | This folder: `assets/previews/` |
+| **Quality** | ~80 for good size/quality balance |
+
+## How to create screenshots
+
+1. In Elementor, create a page and add **one widget per page** (or one section per widget).
+2. Use representative content and the widget’s most useful layout.
+3. Capture the viewport (e.g. 1600×900), then crop/resize to **800×450** and export as WebP.
+4. Save as `{slug}.webp` in this folder.
+
+## Checklist (slug → filename)
+
+Add a file for each slug when you have a screenshot. The onboarding/settings UI will show it automatically.
+
+- `bento-grid.webp`
+- `bento-portfolio.webp`
+- `client-logos.webp`
+- `content-block.webp`
+- `cta-notify.webp`
+- `faq.webp`
+- `feature-grid.webp`
+- `feature-list-cta.webp`
+- `footer.webp`
+- `footer-brand.webp`
+- `form-contact.webp`
+- `grid-case-studies.webp`
+- `grid-components.webp`
+- `grid-posts.webp`
+- `grid-team.webp`
+- `grid-testimonials.webp`
+- `hero-announcement.webp`
+- `hero-centered-image.webp`
+- `hero-collage.webp`
+- `hero-saas.webp`
+- `hero-split.webp`
+- `hero-stacked-image.webp`
+- `intro-pattern.webp`
+- `intro-text.webp`
+- `logo-grid.webp`
+- `nav.webp`
+- `newsletter.webp`
+- `outreach-dashboard.webp`
+- `pipeline-dashboard.webp`
+- `pricing-table.webp`
+- `sales-dashboard.webp`
+- `section-stats.webp`
+- `services.webp`
+- `simple-page-hero.webp`
+- `social-proof.webp`
+- `testimonial-quote.webp`
+
+Until a `.webp` exists for a slug, the UI falls back to the widget’s SVG icon (or category icon).

package/assets/svgs/components/accordion.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <rect x="8" y="6" width="32" height="10" rx="1" />
+  <path d="M16 11h16M16 14h10" />
+  <rect x="8" y="19" width="32" height="10" rx="1" />
+  <path d="M16 24h16M16 27h12" />
+  <rect x="8" y="32" width="32" height="10" rx="1" />
+  <path d="M16 37h16M16 40h8" />
+  <path d="M36 11v2M36 24v2M36 37v2" />
+</svg>

package/assets/svgs/components/alert.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <rect x="6" y="16" width="36" height="16" rx="2" />
+  <path d="M18 24h12M18 28h8" />
+  <path d="M24 10v6" />
+  <circle cx="24" cy="10" r="2" fill="currentColor" />
+</svg>

package/assets/svgs/components/avatar.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <circle cx="24" cy="18" r="8" />
+  <path d="M8 42c0-8.837 7.163-16 16-16s16 7.163 16 16" />
+</svg>

package/assets/svgs/components/badge.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <path d="M10 24a14 10 0 1 0 28 0 14 10 0 1 0-28 0z" />
+  <path d="M22 24l4-4 4 4-2 4h-4z" />
+</svg>

package/assets/svgs/components/breadcrumbs.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <path d="M10 24h2M16 24h2M22 24h2M28 24h2M34 24h2M40 24h2" />
+  <path d="M12 20l2 4-2 4M18 20l2 4-2 4M24 20l2 4-2 4M30 20l2 4-2 4M36 20l2 4-2 4" />
+  <rect x="6" y="18" width="10" height="12" rx="1" />
+  <rect x="20" y="18" width="10" height="12" rx="1" />
+  <rect x="34" y="18" width="10" height="12" rx="1" />
+</svg>

package/assets/svgs/components/button.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <rect x="10" y="14" width="28" height="20" rx="4" />
+  <path d="M20 24h8" />
+</svg>

package/assets/svgs/components/calendar.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <rect x="6" y="10" width="36" height="32" rx="2" />
+  <path d="M6 18h36M16 6v6M32 6v6" />
+  <rect x="10" y="24" width="6" height="6" rx="1" />
+  <rect x="20" y="24" width="6" height="6" rx="1" />
+  <rect x="30" y="24" width="6" height="6" rx="1" />
+  <rect x="10" y="34" width="6" height="6" rx="1" />
+  <rect x="20" y="34" width="6" height="6" rx="1" />
+  <rect x="30" y="34" width="6" height="6" rx="1" />
+</svg>

package/assets/svgs/components/card.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <rect x="6" y="8" width="36" height="32" rx="2" />
+  <rect x="8" y="10" width="32" height="8" rx="1" fill="currentColor" fill-opacity="0.2" stroke="none" />
+  <path d="M12 26h24M12 32h16M12 38h12" />
+</svg>

package/assets/svgs/widgets/bento-grid.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <rect x="4" y="4" width="20" height="18" rx="2" />
+  <rect x="26" y="4" width="18" height="10" rx="2" />
+  <rect x="26" y="16" width="18" height="6" rx="2" />
+  <rect x="4" y="24" width="12" height="20" rx="2" />
+  <rect x="18" y="24" width="14" height="20" rx="2" />
+  <rect x="34" y="24" width="10" height="20" rx="2" />
+</svg>

package/assets/svgs/widgets/bento-portfolio.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <rect x="4" y="4" width="18" height="20" rx="2" />
+  <rect x="24" y="4" width="20" height="12" rx="2" />
+  <rect x="24" y="18" width="10" height="10" rx="2" />
+  <rect x="36" y="18" width="8" height="10" rx="2" />
+  <rect x="4" y="26" width="12" height="18" rx="2" />
+  <rect x="18" y="30" width="18" height="14" rx="2" />
+</svg>

package/assets/svgs/widgets/content-block.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <rect x="6" y="6" width="36" height="36" rx="2" />
+  <path d="M12 14h24M12 20h20M12 26h16M12 32h12" />
+</svg>

package/assets/svgs/widgets/faq.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <rect x="8" y="6" width="32" height="10" rx="2" />
+  <path d="M14 11h16M14 14h10" />
+  <path d="M18 15l-2 2 2 2" />
+  <rect x="8" y="19" width="32" height="10" rx="2" />
+  <path d="M14 24h16M14 27h12" />
+  <path d="M18 28l-2 2 2 2" />
+  <rect x="8" y="32" width="32" height="10" rx="2" />
+  <path d="M14 37h16M14 40h8" />
+  <path d="M18 41l-2 2 2 2" />
+</svg>

package/assets/svgs/widgets/feature-grid.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <rect x="6" y="6" width="16" height="16" rx="2" />
+  <circle cx="12" cy="11" r="2" />
+  <path d="M12 16h6M12 19h4" />
+  <rect x="26" y="6" width="16" height="16" rx="2" />
+  <circle cx="32" cy="11" r="2" />
+  <path d="M32 16h6M32 19h4" />
+  <rect x="6" y="26" width="16" height="16" rx="2" />
+  <circle cx="12" cy="31" r="2" />
+  <path d="M12 36h6M12 39h4" />
+  <rect x="26" y="26" width="16" height="16" rx="2" />
+  <circle cx="32" cy="31" r="2" />
+  <path d="M32 36h6M32 39h4" />
+</svg>

package/assets/svgs/widgets/feature-list-cta.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <circle cx="10" cy="12" r="3" />
+  <path d="M18 12h18M18 16h14" />
+  <circle cx="10" cy="24" r="3" />
+  <path d="M18 24h18M18 28h14" />
+  <circle cx="10" cy="36" r="3" />
+  <path d="M18 36h18M18 40h14" />
+  <rect x="36" y="16" width="8" height="24" rx="2" />
+  <path d="M38 24h4M38 30h4M38 36h4" />
+</svg>

package/assets/svgs/widgets/footer.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <rect x="4" y="8" width="40" height="28" rx="2" />
+  <path d="M10 16h8M10 22h12M10 28h6" />
+  <path d="M26 16h12M26 22h8M26 28h10" />
+  <rect x="4" y="38" width="40" height="6" rx="1" />
+  <path d="M10 42h28" />
+</svg>

package/assets/svgs/widgets/grid-posts.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <rect x="4" y="4" width="12" height="18" rx="2" />
+  <rect x="4" y="24" width="12" height="6" rx="1" />
+  <path d="M8 28h8M8 31h6" />
+  <rect x="18" y="4" width="12" height="18" rx="2" />
+  <rect x="18" y="24" width="12" height="6" rx="1" />
+  <path d="M22 28h6M22 31h4" />
+  <rect x="32" y="4" width="12" height="18" rx="2" />
+  <rect x="32" y="24" width="12" height="6" rx="1" />
+  <path d="M36 28h6M36 31h4" />
+</svg>

package/assets/svgs/widgets/grid-team.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <circle cx="12" cy="12" r="5" />
+  <path d="M6 26c0-3.5 2.7-6 6-6s6 2.5 6 6" />
+  <circle cx="24" cy="12" r="5" />
+  <path d="M18 26c0-3.5 2.7-6 6-6s6 2.5 6 6" />
+  <circle cx="36" cy="12" r="5" />
+  <path d="M30 26c0-3.5 2.7-6 6-6s6 2.5 6 6" />
+</svg>

package/assets/svgs/widgets/hero.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <rect x="4" y="4" width="40" height="32" rx="2" />
+  <path d="M14 16h20M14 22h16M14 28h12" />
+  <rect x="14" y="34" width="12" height="6" rx="2" />
+  <rect x="28" y="20" width="12" height="16" rx="2" />
+  <path d="M30 26h8M30 30h6M30 34h8" />
+</svg>

package/assets/svgs/widgets/intro-text.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <path d="M10 14h28M10 22h24M10 30h20M10 38h16" />
+</svg>

package/assets/svgs/widgets/logo-grid.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <rect x="6" y="10" width="12" height="12" rx="2" />
+  <path d="M10 14h4v4h-4zM14 14h4" />
+  <rect x="22" y="10" width="12" height="12" rx="2" />
+  <circle cx="28" cy="16" r="3" />
+  <rect x="38" y="10" width="4" height="12" rx="1" />
+  <rect x="6" y="26" width="12" height="12" rx="2" />
+  <path d="M10 30h8M10 34h4" />
+  <rect x="22" y="26" width="12" height="12" rx="2" />
+  <path d="M26 30h4v4h-4z" />
+  <rect x="38" y="26" width="4" height="12" rx="1" />
+</svg>

package/assets/svgs/widgets/navigation.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <rect x="4" y="8" width="40" height="8" rx="2" />
+  <path d="M10 12h4M18 12h4M26 12h4M34 12h4" />
+  <rect x="4" y="20" width="40" height="4" rx="1" />
+  <path d="M10 22h28" />
+  <rect x="4" y="28" width="40" height="4" rx="1" />
+  <path d="M10 30h20" />
+  <rect x="4" y="36" width="40" height="4" rx="1" />
+  <path d="M10 38h16" />
+</svg>

package/assets/svgs/widgets/newsletter.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <rect x="6" y="10" width="36" height="28" rx="2" />
+  <path d="M6 14l18 12 18-12" />
+  <rect x="12" y="26" width="24" height="8" rx="1" />
+  <path d="M16 30h16M16 33h12" />
+</svg>

package/assets/svgs/widgets/pricing-table.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <rect x="6" y="6" width="10" height="36" rx="2" />
+  <path d="M10 12h6M10 18h6M10 24h6M10 30h4" />
+  <rect x="19" y="6" width="10" height="36" rx="2" />
+  <rect x="19" y="10" width="10" height="6" rx="1" fill="currentColor" fill-opacity="0.15" stroke="none" />
+  <path d="M23 14h6M23 22h6M23 30h6M23 38h4" />
+  <rect x="32" y="6" width="10" height="36" rx="2" />
+  <path d="M36 12h6M36 18h6M36 24h6M36 30h4" />
+</svg>

package/assets/svgs/widgets/social-proof.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+  <path d="M8 18l3 6 6-8 4 6 3-4 4 2" />
+  <circle cx="10" cy="32" r="5" />
+  <path d="M8 36h4M10 38v-2" />
+  <rect x="20" y="24" width="24" height="20" rx="2" />
+  <path d="M24 30h16M24 36h14M24 42h10" />
+</svg>

package/docs/cursor-global-rule.md

@@ -0,0 +1,24 @@
+# SocialLane Elements — Use Agent Index in All Workspaces
+
+The plugin’s **AGENTS.md** and **.cursor** (skills + agents) are available in every Cursor workspace after a one-time setup.
+
+## What’s already done
+
+- **Skills** and **agents** are copied into your user Cursor directory with a `sociallane-` prefix:
+  - Skills: `~/.cursor/skills/sociallane-*` (e.g. `sociallane-elementor-widget-structure`, `sociallane-animation-controls`, …)
+  - Agents: `~/.cursor/agents/sociallane-*.md` (e.g. `sociallane-plugin-setup.md`, `sociallane-widget-builder.md`, …)
+- A **global index** file was created: `~/.cursor/AGENTS-SocialLane-Elements.md` (same content as AGENTS.md but with user-level paths).
+
+## One-time step: enable the index in all workspaces
+
+Cursor’s **User Rules** (Rules for AI) are global. To have the SocialLane agent index applied in every workspace:
+
+1. Open **Cursor → Settings → Cursor Settings → Rules for AI** (or **Rules → User Rules**).
+2. Paste the contents of **`~/.cursor/AGENTS-SocialLane-Elements.md`** into the Rules for AI text area (append or merge with any existing rules).
+3. Save.
+
+After that, the SocialLane agent index and orchestration rules apply in all workspaces. Skills and agents are loaded from `~/.cursor/skills/` and `~/.cursor/agents/` automatically.
+
+## Syncing updates from the plugin
+
+If the plugin’s **AGENTS.md** or **.cursor/skills** or **.cursor/agents** change, re-run the copy step (or re-run the script/task that copies them into `~/.cursor/` with the `sociallane-` prefix) and, if the index text changed, update **Rules for AI** with the new content from `~/.cursor/AGENTS-SocialLane-Elements.md`.

package/docs/install-new-instance.md

@@ -0,0 +1,92 @@
+# Installing SocialLane Elements in a New Instance
+
+This plugin lives in its own Git repo and can be installed in any WordPress instance.
+
+## Repo
+
+- **URL:** `https://github.com/Mitch00llK/sociallane-elements.git`
+- **Visibility:** Private (requires GitHub access)
+
+---
+
+## Option 1: Clone into plugins
+
+```bash
+cd wp-content/plugins
+git clone https://github.com/Mitch00llK/sociallane-elements.git
+cd sociallane-elements
+npm install
+```
+
+`npm run build` runs automatically after `npm install` (postinstall). For a full setup (Node version check, optional minimal `widgets.json`), run:
+
+```bash
+npm run setup
+```
+
+Activate the plugin in WordPress → Plugins.
+
+---
+
+## Option 2: Add as submodule (recommended for versioned projects)
+
+If your site uses Git and you want to track the plugin as a submodule:
+
+```bash
+cd wp-content/plugins
+git submodule add https://github.com/Mitch00llK/sociallane-elements.git
+cd sociallane-elements
+git submodule update --init --recursive
+npm install && npm run build
+```
+
+After cloning the parent project elsewhere:
+
+```bash
+git submodule update --init --recursive
+cd wp-content/plugins/sociallane-elements && npm install && npm run build
+```
+
+---
+
+## Option 3: Install from npm
+
+If the plugin is published to npm (e.g. `@sociallane/elements`):
+
+```bash
+# From your project root or any directory
+npm install @sociallane/elements
+```
+
+Then copy the package into WordPress plugins and install its dependencies:
+
+```bash
+cp -r node_modules/@sociallane/elements wp-content/plugins/sociallane-elements
+cd wp-content/plugins/sociallane-elements
+npm install
+```
+
+`npm install` runs postinstall (syncs `widgets.json` and builds). Activate the plugin in WordPress → Plugins.
+
+To install directly into `wp-content/plugins` without a project root:
+
+```bash
+cd wp-content/plugins
+npm install @sociallane/elements
+mv node_modules/@sociallane/elements ./sociallane-elements
+rmdir node_modules 2>/dev/null || true
+cd sociallane-elements && npm install
+```
+
+---
+
+## Post-install
+
+1. **Build:** Runs automatically after `npm install`. To run manually: `npm run build`.
+2. **Widget selection:** Edit `widgets.json` to load only the widgets you need. If missing, `npm run setup` creates it from `widgets.json.minimal`.
+3. **Production mode:** Add to `wp-config.php` if styles don't load:
+   ```php
+   define( 'SOCIALLANE_ELEMENTS_VITE_PRODUCTION', true );
+   ```
+
+See [package-installation.md](package-installation.md) and [npm-widget-cheatsheet.md](npm-widget-cheatsheet.md) for details.