expxagents 0.1.0

package/assets/core/best-practices/landing-page.md

@@ -0,0 +1,279 @@
+# Landing Page — Best Practices
+
+## Princípios de Design
+
+### 1. Design System First
+Toda landing page DEVE começar com um design system definido via CSS custom properties. Zero valores hardcoded.
+
+```css
+:root {
+  /* === CORE TOKENS === */
+  /* Colors — use off-black/off-white, never pure #000/#fff */
+  --color-base-900: #0f172a;
+  --color-base-800: #1e293b;
+  --color-base-700: #334155;
+  --color-base-100: #f1f5f9;
+  --color-base-50: #f8fafc;
+  --color-white: #ffffff;
+
+  /* Accent — single brand color + hover state */
+  --color-accent: oklch(0.65 0.25 15);    /* vibrant, perceptually uniform */
+  --color-accent-hover: oklch(0.58 0.25 15);
+  --color-accent-subtle: oklch(0.65 0.25 15 / 0.1);
+
+  /* Semantic */
+  --color-surface: var(--color-white);
+  --color-surface-alt: var(--color-base-50);
+  --color-surface-dark: var(--color-base-900);
+  --color-on-surface: var(--color-base-800);
+  --color-on-surface-muted: var(--color-base-700);
+  --color-on-dark: var(--color-base-50);
+  --color-success: oklch(0.72 0.19 150);
+
+  /* === SPACING (4px base unit) === */
+  --space-1: 0.25rem;   /* 4px */
+  --space-2: 0.5rem;    /* 8px */
+  --space-3: 0.75rem;   /* 12px */
+  --space-4: 1rem;      /* 16px */
+  --space-6: 1.5rem;    /* 24px */
+  --space-8: 2rem;      /* 32px */
+  --space-12: 3rem;     /* 48px */
+  --space-16: 4rem;     /* 64px */
+  --space-20: 5rem;     /* 80px */
+  --space-24: 6rem;     /* 96px */
+  --space-32: 8rem;     /* 128px */
+
+  /* Section spacing — generous */
+  --section-py: clamp(var(--space-16), 10vw, var(--space-32));
+  --section-px: var(--space-6);
+  --container-max: 1200px;
+  --container-narrow: 720px;
+
+  /* === TYPOGRAPHY === */
+  --font-display: 'Plus Jakarta Sans', 'Inter', system-ui, sans-serif;
+  --font-body: 'Inter', system-ui, sans-serif;
+  --font-mono: 'JetBrains Mono', 'Fira Code', monospace;
+
+  /* Fluid type scale — min @ 320px, max @ 1200px */
+  --text-display: clamp(2.5rem, 5vw + 1rem, 4.5rem);
+  --text-h1: clamp(2rem, 4vw + 0.5rem, 3.5rem);
+  --text-h2: clamp(1.5rem, 3vw + 0.25rem, 2.25rem);
+  --text-h3: clamp(1.125rem, 2vw + 0.25rem, 1.5rem);
+  --text-body: clamp(1rem, 1vw + 0.5rem, 1.125rem);
+  --text-small: 0.875rem;
+  --text-caption: 0.75rem;
+
+  --leading-tight: 1.15;
+  --leading-normal: 1.6;
+  --leading-relaxed: 1.8;
+
+  --tracking-tight: -0.02em;
+  --tracking-normal: 0;
+  --tracking-wide: 0.05em;
+  --tracking-widest: 0.1em;
+
+  /* === RADIUS === */
+  --radius-sm: 0.375rem;   /* 6px — inputs, small elements */
+  --radius-md: 0.75rem;    /* 12px — cards, containers */
+  --radius-lg: 1rem;       /* 16px — featured cards */
+  --radius-xl: 1.5rem;     /* 24px — hero elements */
+  --radius-full: 9999px;   /* pills, avatars */
+
+  /* === SHADOWS (multi-layered for realism) === */
+  --shadow-sm:
+    0 1px 2px oklch(0 0 0 / 0.04),
+    0 1px 3px oklch(0 0 0 / 0.06);
+  --shadow-md:
+    0 2px 4px oklch(0 0 0 / 0.04),
+    0 4px 8px oklch(0 0 0 / 0.06),
+    0 8px 16px oklch(0 0 0 / 0.04);
+  --shadow-lg:
+    0 4px 8px oklch(0 0 0 / 0.03),
+    0 8px 16px oklch(0 0 0 / 0.06),
+    0 16px 32px oklch(0 0 0 / 0.06),
+    0 32px 64px oklch(0 0 0 / 0.04);
+  --shadow-xl:
+    0 8px 16px oklch(0 0 0 / 0.04),
+    0 16px 32px oklch(0 0 0 / 0.08),
+    0 32px 64px oklch(0 0 0 / 0.08),
+    0 64px 128px oklch(0 0 0 / 0.06);
+  --shadow-accent:
+    0 4px 12px oklch(0.65 0.25 15 / 0.25),
+    0 8px 24px oklch(0.65 0.25 15 / 0.15);
+
+  /* === TRANSITIONS === */
+  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
+  --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
+  --duration-fast: 150ms;
+  --duration-normal: 250ms;
+  --duration-slow: 400ms;
+}
+```
+
+### 2. Layout Patterns
+
+**Container:**
+```css
+.container {
+  max-width: var(--container-max);
+  margin: 0 auto;
+  padding: 0 var(--section-px);
+}
+.container--narrow { max-width: var(--container-narrow); }
+```
+
+**Section rhythm — alternating density:**
+```
+[HERO — full-bleed, dense, dark]
+[PROBLEM — spacious, light, breathing room]
+[SOLUTION — medium density, alternating columns]
+[PROOF — full-bleed, dark, contrasting]
+[CTA — full-bleed, gradient, dense]
+```
+
+**Grid patterns:**
+- Stats/numbers: `grid-template-columns: repeat(auto-fit, minmax(200px, 1fr))`
+- Cards: `grid-template-columns: repeat(auto-fill, minmax(300px, 1fr))`
+- Two-column content: `grid-template-columns: 1fr 1fr` with `gap: var(--space-16)`
+- Asymmetric: `grid-template-columns: 1.2fr 0.8fr`
+
+### 3. Typography Rules
+
+- **Display (hero):** --font-display, weight 800, --leading-tight, --tracking-tight
+- **Headings:** --font-display, weight 700, --leading-tight
+- **Body:** --font-body, weight 400-500, --leading-normal
+- **Labels/badges:** --font-body, weight 600, uppercase, --tracking-widest, --text-caption
+- **NEVER** use font-size less than 16px for body text on mobile
+- **ALWAYS** use clamp() for fluid sizing between breakpoints
+
+### 4. Color Usage
+
+- Background alternation: --color-surface → --color-surface-alt → --color-surface-dark
+- Text: --color-on-surface for primary, --color-on-surface-muted for secondary
+- Accent: ONLY on CTAs, key numbers, highlights, and active states (<15% of page)
+- Gradients: Use subtle gradients (same hue, different lightness) for backgrounds
+- Never use opacity for text colors — use explicit muted color tokens
+
+### 5. Component Patterns
+
+**Button/CTA:**
+```css
+.btn-primary {
+  background: var(--color-accent);
+  color: var(--color-white);
+  padding: var(--space-4) var(--space-8);
+  border-radius: var(--radius-md);
+  font-weight: 700;
+  font-size: var(--text-body);
+  box-shadow: var(--shadow-accent);
+  transition: all var(--duration-normal) var(--ease-out);
+}
+.btn-primary:hover {
+  background: var(--color-accent-hover);
+  transform: translateY(-2px);
+  box-shadow: var(--shadow-lg);
+}
+```
+
+**Card:**
+```css
+.card {
+  background: var(--color-surface);
+  border-radius: var(--radius-lg);
+  padding: var(--space-8);
+  box-shadow: var(--shadow-md);
+  border: 1px solid oklch(0 0 0 / 0.05);
+  transition: all var(--duration-normal) var(--ease-out);
+}
+.card:hover {
+  transform: translateY(-4px);
+  box-shadow: var(--shadow-lg);
+}
+```
+
+**Badge/Pill:**
+```css
+.badge {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-1) var(--space-3);
+  border-radius: var(--radius-full);
+  font-size: var(--text-caption);
+  font-weight: 600;
+  letter-spacing: var(--tracking-wide);
+  text-transform: uppercase;
+  background: var(--color-accent-subtle);
+  color: var(--color-accent);
+}
+```
+
+### 6. Animation Guidelines
+
+**Scroll reveals (IntersectionObserver):**
+```css
+.reveal {
+  opacity: 0;
+  transform: translateY(24px);
+  transition: opacity var(--duration-slow) var(--ease-out),
+              transform var(--duration-slow) var(--ease-out);
+}
+.reveal.visible {
+  opacity: 1;
+  transform: translateY(0);
+}
+```
+
+- Stagger children: `transition-delay: calc(var(--index) * 80ms)`
+- Only animate `opacity` and `transform` — never width, height, margin, or padding
+- Use `will-change: transform, opacity` on animated elements
+- Respect `prefers-reduced-motion` media query
+
+### 7. Responsive Strategy
+
+- Mobile-first: base styles are mobile, media queries add desktop
+- Breakpoints: 640px (sm), 768px (md), 1024px (lg), 1280px (xl)
+- Use `clamp()` for fluid values between breakpoints
+- Stack columns on mobile, grid on desktop
+- Touch targets: minimum 44x44px on mobile
+- Hide non-essential content on mobile (less is more)
+
+### 8. Performance Requirements
+
+- Single HTML file with inline CSS and JS
+- Fonts: max 2 families, preconnect + font-display: swap
+- Images: WebP, lazy loading, explicit dimensions (aspect-ratio)
+- JS: vanilla only, defer/async, IntersectionObserver for scroll effects
+- Target: Lighthouse 95+ on all categories
+- Above-the-fold content must render without JS
+
+### 9. Accessibility Minimum
+
+- Semantic HTML: header, nav, main, section, article, footer
+- Heading hierarchy: single H1, sequential H2-H6
+- Color contrast: 4.5:1 for text, 3:1 for UI elements
+- Focus-visible on all interactive elements
+- ARIA attributes on custom widgets (accordion, modal)
+- Skip-to-content link
+- Form labels and error messages
+- lang attribute on html element
+
+### 10. Quality Checklist
+
+Before finalizing any landing page:
+
+- [ ] All values use CSS custom properties (zero hardcoded)
+- [ ] Typography uses clamp() for fluid sizing
+- [ ] Shadows are multi-layered (min 2 layers)
+- [ ] Whitespace between sections is generous (80-128px)
+- [ ] Max 3 colors used (base + surface + accent)
+- [ ] CTAs have accent shadow (--shadow-accent)
+- [ ] Cards/elements have subtle borders (1px, <5% opacity)
+- [ ] Scroll animations use IntersectionObserver
+- [ ] Respects prefers-reduced-motion
+- [ ] Mobile-first CSS with min-width media queries
+- [ ] All images have alt text
+- [ ] Form inputs have associated labels
+- [ ] Focus states are visible and styled
+- [ ] Lighthouse score >90 in all categories
+- [ ] "Squint test" passes — hierarchy is clear at a glance

package/assets/core/best-practices/linkedin-article.md

@@ -0,0 +1,83 @@
+---
+platform: linkedin
+format: article
+constraints:
+  max_chars: null
+  image_ratio: "1.91:1"
+  max_hashtags: 5
+---
+
+# Best Practices: LinkedIn — Article
+
+## Format Rules
+
+- No character limit; ideal length is 1500–3000 words for depth without drop-off
+- Title: up to 100 characters; should include the primary keyword
+- Cover image: 1200x627px minimum; shown prominently in article header and feed preview
+- Supports full rich text: headers (H1–H3), bold, italic, bullet lists, numbered lists, block quotes, images, and embedded media
+- Articles are indexed by LinkedIn search and Google — treat them as SEO assets
+- Published articles appear in the "Articles" tab of your profile permanently
+
+## Structure
+
+```
+[TITLE — keyword-forward, benefit-driven, under 70 characters]
+
+[COVER IMAGE — relevant, high quality]
+
+[INTRODUCTION — 100–150 words]
+- Hook sentence
+- State the problem or opportunity
+- Preview what the reader will get
+
+[H2 SECTION 1 — first main point]
+[2–3 paragraphs, each under 100 words]
+
+[H2 SECTION 2 — second main point]
+[Include an example, case study, or data point]
+
+[H2 SECTION 3 — practical application]
+[Numbered list or actionable steps]
+
+[PULL QUOTE — one memorable sentence formatted as block quote]
+
+[CONCLUSION — 100–150 words]
+- Summarize key takeaways
+- Reinforce the transformation
+- End with a call to action (share, comment, follow)
+```
+
+## Guidelines
+
+- **Thought leadership, not content marketing.** Articles should advance a real argument or reveal a genuine insight, not just summarize common knowledge.
+- Open with a story, a counterintuitive claim, or a specific scenario — not background context.
+- Use H2 and H3 headers generously; they improve readability and LinkedIn search indexing.
+- Include one original data point, personal case study, or proprietary framework per article.
+- Link to external sources sparingly; keep readers in the article.
+- Add a professional author bio section at the end with a link to your profile or website.
+- Republish blog content to LinkedIn Articles after a 2-week delay (canonical URL won't conflict significantly).
+- Share the article as a native post to get initial distribution; articles alone have limited feed visibility.
+
+## Examples
+
+**Strong title patterns:**
+- "The Hidden Cost of [Common Practice] (And What to Do Instead)"
+- "How [Company/Person] Achieved [Result] Using [Method]"
+- "Why [Popular Belief] Is Wrong — And What the Data Shows"
+
+**Introduction template:**
+```
+[Opening line that challenges an assumption or tells a story]
+
+[1–2 sentences of context]
+
+In this article, I'll share [specific takeaway 1], [specific takeaway 2], and [specific takeaway 3] — based on [your experience/data/research].
+
+[Transition sentence that pulls the reader into Section 1]
+```
+
+**Conclusion CTA:**
+```
+If this resonated, share it with someone navigating the same challenge.
+I publish one article each month on [topic]. Follow me to stay in the loop.
+```

package/assets/core/best-practices/linkedin-post.md

@@ -0,0 +1,84 @@
+---
+platform: linkedin
+format: post
+constraints:
+  max_chars: 3000
+  image_ratio: "1.91:1"
+  max_hashtags: 5
+---
+
+# Best Practices: LinkedIn — Feed Post
+
+## Format Rules
+
+- Character limit: 3000 characters
+- Preview cutoff: ~210 characters before "...see more" on desktop; ~140 on mobile
+- Images: 1200x627px (1.91:1) for single images; 1080x1080px also works well
+- Hashtags: 3–5 is the LinkedIn-recommended range; more dilutes reach
+- No external links in the post body — they suppress reach. Use first comment for links.
+- Polls, documents (carousels), and native video get boosted distribution
+
+## Structure
+
+```
+[HOOK — 1–2 lines, no period, make them click "see more"]
+
+[BLANK LINE]
+
+[SETUP — 2–3 lines establishing context or problem]
+
+[BLANK LINE]
+
+[BODY — 3–7 short paragraphs or a numbered/bulleted list]
+- Each point on its own line
+- White space is critical for readability
+
+[BLANK LINE]
+
+[PERSONAL INSIGHT or LESSON]
+
+[BLANK LINE]
+
+[CTA — one direct question to invite comments]
+
+[HASHTAGS — 3–5 at the end]
+```
+
+## Guidelines
+
+- **Lead with the hook, not with context.** "I was wrong about X" beats "Let me share some thoughts about X."
+- Write conversationally. LinkedIn users skim; short paragraphs hold attention.
+- Personal stories outperform general advice by 3–5x engagement. "I" > "You" > "One."
+- End with an open question that is easy to answer in one sentence — lowers the comment friction.
+- Engage within the first 60 minutes after posting to signal activity to the algorithm.
+- Tag people sparingly and only when directly relevant — avoid tag-baiting.
+- Native documents (uploaded PDFs formatted as carousels) have the highest dwell time.
+- Post 3–5 times per week for consistent reach growth.
+
+## Examples
+
+**Hook variants:**
+- "I turned down a $500K offer. Here's why."
+- "3 things every senior engineer knows that junior engineers don't"
+- "My biggest career mistake — and what it taught me"
+
+**Full post (condensed):**
+```
+I spent 2 years building the wrong product.
+
+We had 100+ users. Revenue was growing. The team was motivated.
+
+But I ignored every signal that told me to pivot.
+
+Here's what I learned:
+
+1. Revenue isn't validation — it's a lagging indicator
+2. Churn rate tells the real story
+3. Your best users are not your average users
+
+The hardest decision isn't to quit. It's to redirect.
+
+What's a hard pivot you've made that you don't regret?
+
+#startups #productmanagement #entrepreneurship
+```

package/assets/core/best-practices/researching.md

@@ -0,0 +1,89 @@
+---
+platform: universal
+format: research
+constraints:
+  max_chars: null
+  image_ratio: null
+  max_hashtags: null
+---
+
+# Best Practices: Research Methodology
+
+## Core Principles
+
+Quality research is the foundation of credible content. It involves systematic source discovery, critical evaluation, and structured synthesis.
+
+- **Primary over secondary.** Original data, firsthand accounts, and official publications outweigh summaries and aggregations.
+- **Triangulate claims.** Any key fact should be verified by at least 2–3 independent sources.
+- **Date everything.** A statistic from 2018 may be misleading in 2025. Always surface the publication date.
+- **Follow the chain.** When a source cites a study, find and read the original study — not the summary.
+
+## Research Process
+
+### Phase 1: Define the Research Question
+- State the specific question being answered
+- Identify what type of evidence is needed (quantitative, qualitative, expert opinion, case study)
+- Define the scope: time range, geography, industry, audience
+
+### Phase 2: Source Discovery
+- Academic: Google Scholar, PubMed, ResearchGate, JSTOR
+- Industry: Gartner, Forrester, McKinsey, Statista, Nielsen
+- News: Reuters, AP, Bloomberg, industry trade publications
+- Primary: original surveys, interviews, experiments, official reports
+- Social: forums, communities (Reddit, Quora) for sentiment and pain points (not as citable fact)
+
+### Phase 3: Source Evaluation — SIFT Method
+- **Stop** — pause before sharing or using any source
+- **Investigate the source** — who wrote it, who published it, what are their incentives?
+- **Find better coverage** — look for the original source or corroboration
+- **Trace claims** — follow citations back to their origin
+
+### Phase 4: Synthesis
+- Group findings by theme, not by source
+- Note consensus vs. disagreement across sources
+- Identify gaps in the existing research
+
+## Structure
+
+```
+[RESEARCH BRIEF]
+- Question:
+- Context:
+- Required evidence type:
+- Date range:
+
+[SOURCE LIST]
+- Source 1: [Title, Author, Publication, Date, URL]
+- Source 2: ...
+- Credibility rating: High / Medium / Low
+
+[KEY FINDINGS]
+- Finding 1: [Claim] — Source: [Citation] — Date: [YYYY]
+- Finding 2: ...
+
+[GAPS AND CAVEATS]
+- What the research does NOT address
+- Potential biases in the sources
+
+[SYNTHESIS]
+- What the evidence collectively supports
+- Recommended interpretation for the content piece
+```
+
+## Guidelines
+
+- Reject statistics without a clear source. "Studies show..." with no citation is not evidence.
+- Note the difference between correlation and causation in quantitative findings.
+- For content, prefer the most recent data available — but note when a dated source is used.
+- When expert opinions conflict, present the disagreement honestly rather than cherry-picking.
+- Keep a research log for every project; it enables fact-checking and updates later.
+- Wikipedia is acceptable for orientation — not as a primary citation.
+
+## Source Quality Tiers
+
+| Tier | Examples | Use For |
+|------|----------|---------|
+| 1 - Primary | Original studies, official data, direct interviews | Core claims, statistics |
+| 2 - Expert | Industry reports, peer-reviewed journals | Supporting evidence |
+| 3 - Reputable media | Reuters, NYT, Bloomberg | Context and news |
+| 4 - Secondary | Blogs, influencers, aggregators | Leads to primary sources only |

package/assets/core/best-practices/review.md

@@ -0,0 +1,95 @@
+---
+platform: universal
+format: content-review
+constraints:
+  max_chars: null
+  image_ratio: null
+  max_hashtags: null
+---
+
+# Best Practices: Content Review and Quality Assurance
+
+## Core Principles
+
+A content review is not just proofreading — it is a structured quality gate that ensures accuracy, brand alignment, strategic fit, and platform appropriateness before publication.
+
+- Review with fresh eyes: wait at least 30 minutes after writing before reviewing.
+- Review for the reader, not the writer — what the audience will understand matters more than what the author intended.
+- Use a checklist, not memory — cognitive load causes reviewers to miss consistent categories of errors.
+
+## Review Layers
+
+### Layer 1: Structural Review
+- Does the piece fulfill its stated objective?
+- Is the structure logical and easy to navigate?
+- Is the hook strong enough for the platform?
+- Is the CTA clear, singular, and appropriate?
+
+### Layer 2: Accuracy Review
+- Are all statistics cited with a source and date?
+- Are all factual claims verifiable?
+- Are product names, brand names, and prices correct?
+- Are there any legal or compliance risks (unverified health claims, competitor comparisons, testimonials)?
+
+### Layer 3: Brand and Voice Review
+- Does the tone match the brand voice guide?
+- Are brand-specific terminology and spellings consistent?
+- Is the content appropriate for the audience (reading level, cultural sensitivity)?
+
+### Layer 4: Platform Review
+- Does the format meet platform constraints (character limits, image specs, hashtag counts)?
+- Is the content optimized for the platform's algorithm (SEO keywords, engagement triggers)?
+- Are links, tags, and mentions correct?
+
+### Layer 5: Copy Edit
+- Grammar, spelling, and punctuation
+- Sentence flow and readability (aim for Flesch-Kincaid Grade 7–9 for general audiences)
+- Consistency in tense, voice, and formatting
+
+## Structure (Review Report)
+
+```
+[CONTENT TITLE / ID]
+[REVIEWER NAME]
+[REVIEW DATE]
+[PLATFORM AND FORMAT]
+
+[SUMMARY VERDICT]
+- Status: Approved / Approved with changes / Requires revision / Rejected
+- Priority issues: [list]
+
+[STRUCTURAL NOTES]
+[ACCURACY FLAGS]
+[BRAND ALIGNMENT NOTES]
+[PLATFORM COMPLIANCE NOTES]
+[COPY EDITS — inline or attached]
+
+[REVISION REQUIRED BY (date)]
+```
+
+## Guidelines
+
+- Never approve content with unverified statistics or missing source citations.
+- Flag but do not unilaterally change strategic decisions — escalate to the content strategist.
+- Use a shared annotation tool (Google Docs comments, Notion inline comments) to keep feedback traceable.
+- Distinguish between required changes and suggested improvements — use clear labels.
+- Final approval requires sign-off from at least one reviewer who did not write the content.
+- For regulated industries (health, finance, legal), require specialist compliance review before publishing.
+
+## Review Checklist Template
+
+```
+[ ] Objective clearly met
+[ ] Hook appropriate for platform
+[ ] One clear CTA
+[ ] All facts cited with source + date
+[ ] No unverifiable claims
+[ ] Brand voice consistent
+[ ] No competitor disparagement without legal clearance
+[ ] Platform constraints met (chars, image specs, hashtags)
+[ ] SEO/algorithm elements present (keywords, alt text)
+[ ] Grammar and spelling clean
+[ ] All links functional
+[ ] Author bio / attribution correct (if applicable)
+[ ] Legal/compliance sign-off (if required)
+```