# lilAgents Full Documentation --- # FILE: company-profile.md # Company Profile - lilAgents > Digital agency for founders who are tired of paying monthly for things that aren't really theirs. ## What We Do lilAgents builds websites, brands, marketing systems, and custom tools that belong to the client, not the platform or the agency. Nothing we ship is engineered to lock you in, and anything we plug in is portable and easy to migrate. You own it, we manage it. Core services: - Websites built on open, portable stacks - Brand and design work delivered as real source files - Marketing, SEO, and content that compound into real search equity - Lead generation and outbound running through your own accounts - Custom tools and internal software when the off-the-shelf option doesn't fit ## Why It Works We use AI agents and modern automation to do more with less overhead. Project builds ship in weeks, not months, and retainers cost less because we run lean. Our team has 15+ years of average experience serving clients in legal, restaurant, real estate, healthcare, staffing, ecommerce, software development, and cloud optimization. Every build is bespoke, not spun up from an outdated template. ## Products - **lilHub**: Link-in-bio platform with custom domains and analytics - **lilHelper**: Browser extension for content conversion and productivity - **lilSignature**: Email signature management tool ## Contact - Website: [lilagents.com](https://lilagents.com) - Email: support@lilagents.com - Location: Seattle, WA ## Case Studies View recent work at [lilagents.com/case-studies](https://lilagents.com/case-studies/). --- # FILE: instructions.md # Agent Instructions - lilAgents > This is the main entry point for AI agents working on the lilAgents codebase. For project structure and technical setup, refer to [replit.md](../replit.md). ## Quick Reference | Guide | Purpose | Location | |-------|---------|----------| | **Brand Voice** | Writing style, tone, phrases to avoid | [brand-voice.md](brand-voice.md) | | **Style Guide** | Typography, colors, component patterns | [style-guide.md](style-guide.md) | | **Company Profile** | Mission, services, and products | [company-profile.md](company-profile.md) | | **Project Docs** | Technical architecture, setup, dependencies | [replit.md](../replit.md) | --- ## Blog Content Guidelines For comprehensive blog writing guidelines, see [brand-voice.md](brand-voice.md). ### Blog Post Structure Every blog post requires frontmatter in YAML format: ```yaml --- title: Your Blog Post Title publishDate: YYYY-MM-DD lastUpdated: YYYY-MM-DD # ALWAYS add when updating existing posts snippet: A compelling 1-2 sentence description for previews and SEO imageSrc: "[[images/filename.png]]" imageAlt: Descriptive alt text for accessibility showCover: true tags: - Marketing - Development draft: false author: Author Name authorImgSrc: /assets/team/name.jpg authorImgAlt: Author Name quotesQuote: "Quote text for [!quote] marker" quotesAuthor: Quote Attribution ctaText: Call-to-action paragraph text ctaButtonText: Button Label ctaButtonLink: /path-or-url targetKeyword: primary seo keyword --- ``` ### Special Markers | Marker | Purpose | Requires Frontmatter | |--------|---------|---------------------| | `[!cta]` | Call-to-action block | `ctaText`, `ctaButtonText`, `ctaButtonLink` | | `[!quote]` | Styled quote block | `quotesQuote`, `quotesAuthor` | | `> [!info]` | Info callout | None | | `> [!tip]` | Tip callout | None | | `> [!warning]` | Warning callout | None | | `==text==` | Highlighted text | None | | `[^1]` | Footnote reference | Footnote definition | ### Critical Rules 1. **Always update `lastUpdated`** when modifying any existing blog post 2. **Never skip heading levels** (H2 > H3 > H4, never H2 directly to H4) 3. **Include 2-3 internal links** to other lilAgents content 4. **Use descriptive alt text** for all images --- ## Visual Design Guidelines For comprehensive design guidelines, see [style-guide.md](style-guide.md). ### Typography Quick Reference | Element | Classes | Max Size | |---------|---------|----------| | H1 | `text-3xl sm:text-4xl font-bold` | 36px | | H2 | `text-2xl sm:text-3xl font-semibold` | 30px | | H3 | `text-lg font-semibold` | 18px | ### Background Colors Alternate between these for visual separation: - Primary: `bg-white dark:bg-dark` - Secondary: `bg-gray-1 dark:bg-dark-2` - Accent: `bg-primary` --- ## Case Study Pages When creating new case study pages, copy the template from `/src/pages/case-studies/firehouse-lawyer.astro`. ### Required Data Properties ```javascript const caseStudy = { title: "Client Name", subtitle: "Brief tagline", industry: "Industry", client: "Company Name", location: "City, State", website: "https://...", coverImage: "/assets/case-studies/...", coverImageAlt: "Descriptive alt text", hasVideo: true/false, // Set to true if video testimonial exists videoUrl: "https://youtube...", // Only if hasVideo is true videoTitle: "Video title", // Only if hasVideo is true challenge: { /* ... */ }, solution: { /* ... */ }, results: { /* ... */ }, testimonial: { /* ... */ }, services: ["Service 1", "Service 2"] }; ``` ### Background Alternation The template automatically handles background color alternation based on `hasVideo`: - When `hasVideo: true`: Video section appears, backgrounds alternate correctly - When `hasVideo: false`: Video section is hidden, backgrounds still alternate correctly --- ## Asset Upload Rules The `attached_assets/` folder is for TEMPORARY storage only. Always move uploaded files to their permanent location: | Asset Type | Permanent Location | |------------|-------------------| | Blog images | `src/content/blog/images/` | | Team photos | `public/assets/team/` | | Client logos | `public/assets/logos/` | | Case study images | `public/assets/case-studies/` | | General site images | `public/assets/` | --- ## Quality Checklist Before completing any task: - [ ] Typography follows the heading hierarchy - [ ] Backgrounds alternate properly between sections - [ ] All images have descriptive alt text - [ ] Links work correctly (internal and external) - [ ] Responsive design works on mobile - [ ] Dark mode styling is correct - [ ] No AI-sounding phrases in content (see brand-voice.md) --- *Last updated: February 5, 2026* --- # FILE: brand-voice.md # Brand Voice & Writing Guidelines > This document provides comprehensive guidance for AI agents and human writers creating content for lilAgents. Focus on sounding human, being practical, and providing actionable value. ## Core Identity lilAgents is an AI-native digital agency for founders who are tired of paying monthly for things that aren't really theirs. The brand line is **Growth you actually own**, and the operating posture is **You own it, we manage it**. We build websites, brands, marketing systems, and custom tools that belong to the client on day one, on portable infrastructure that any competent developer could pick up if we ever stepped away. Anything we plug in is portable and easy to migrate. The team has 15+ years of combined experience across legal, restaurant, real estate, healthcare, staffing, ecommerce, software, and cloud optimization. AI agents and modern automation let us run leaner than legacy agencies, which is how we ship in weeks instead of months and charge less while doing it. ### Brand archetype: Outlaw plus Sage We embody the Outlaw archetype tempered by the Sage's experience. The Outlaw is the engine of the positioning: we exist because the legacy agency model quietly turns client websites, brands, and marketing systems into subscriptions, and we refuse to participate. The Sage is what keeps the rebellion from sounding like a pose: 15+ years of hands-on work across the verticals we serve, and a track record of shipped client outcomes we can point at by name. Practical implication for voice: we're willing to call out how the agency world has been operating, but we do it from a position of expertise rather than contrarianism for its own sake. The voice should never sound smug about its own correctness, and it should never sound like a complaint without a solution attached. ### Audience framing: founder to founder The reader is almost always the founder of a small to mid-sized business who has been burned at least once by an agency or platform. They distrust jargon. They value people who can explain things without it. They want to pick up the phone and talk to someone who has actually built the thing being discussed. Write to them as a peer, not a prospect. Use "we" and "you" the way two founders comparing notes would, not the way a sales deck does. ## Voice Characteristics | Trait | Description | Example | |-------|-------------|---------| | **Conversational** | Write like you're talking to a smart colleague, not lecturing a classroom | "Let's break it down step by step" instead of "The following sections will enumerate" | | **Direct** | Get to the point. Cut the fluff. | "Most folks are measuring the wrong things" instead of "It is frequently observed that many marketing professionals may not be tracking optimal metrics" | | **Confident but not arrogant** | Share expertise without condescension | "We've seen this a ton over 15+ years" - shows credibility without bragging | | **Practical** | Every piece of content should provide actionable value | Include specific steps, tools, or frameworks readers can implement | | **Authentic** | Sound human, not AI-generated | Avoid overused AI phrases like "In today's fast-paced world" or "It's important to note that" | | **Founder to founder** | Talk like a peer comparing notes with another founder, not a vendor pitching a buyer | "Most founders I've talked to keep paying monthly for tools they can't actually leave" instead of "Our enterprise clients leverage best-in-class solutions" | | **Plain-spoken contrarian** | Willing to name what's broken about how legacy agencies operate, but always from a position of experience | "Most agencies pin your hosting and ad accounts to their logins. We don't, because we don't need the lock-in to keep your business" instead of vague claims about being different | ## Writing Patterns to Emulate 1. **First-person plural when representing lilAgents**: "We've seen...", "Our team...", "We recommend..." 2. **Direct address to reader**: "If you're struggling with...", "You might be wondering..." 3. **Casual transitions**: "Let's be real:", "Here's the truth:", "So, what do you actually do?" 4. **Honest acknowledgment of complexity**: "This is where most dashboards fall short", "It's not their fault" ## Patterns to Avoid - **AI-sounding phrases**: "In the realm of", "Delve into", "It's worth noting", "At the end of the day" - **Excessive hedging**: "might possibly", "could potentially" - **Empty transitions**: "Furthermore", "Moreover", "Additionally" (at the start of every paragraph) - **Overuse of em dashes**: While em dashes are fine, excessive use signals AI writing - **Generic conclusions**: "In conclusion", "To sum up" --- ## Phrases to Avoid (AI Detection Blocklist) The following words and phrases are overused in AI-generated content and should be avoided or replaced. ### Transitional Words & Filler Phrases | Avoid | Use Instead | |-------|-------------| | Indeed | (remove, or use "Yes" sparingly) | | Furthermore | Also, Plus, And | | However | But, Though, Still | | Moreover | Also, And, Plus | | Subsequently | Then, Later, After that | | Accordingly | So, Therefore | | Notably | (remove, just state the fact) | | Therefore | So | | Additionally | Also, And | | Consequently | So, As a result | | Thus | So | | In terms of | For, About, Regarding | | Significantly | (remove, or be specific about degree) | ### Preamble & Filler Phrases | Avoid | Use Instead | |-------|-------------| | It is important to note that | (just state the fact) | | It's worth mentioning that | (just mention it) | | It is worth noting that | (just note it) | | It is crucial to understand | (just explain it) | | It is essential to consider | (just explain why) | | It is generally considered | People generally think... | | As a matter of fact | Actually, In fact | | In light of the fact that | Because, Since | | Given the fact that | Because, Since | | Bearing in mind that | Considering, Since | | You may want to check | Check... | | Can vary depending on what | Depends on... | | In this article/guide/blog post | (remove entirely or be more direct) | ### Cliched Marketing Phrases | Avoid | Use Instead | |-------|-------------| | Revolutionize the way | (describe the specific change) | | Cutting-edge | Innovative, New, Modern, (be specific) | | Unlock the potential of | Get more from, Improve | | Unleash the power of | Use, Take advantage of | | Delve into the world of | Explore, Learn about | | Pave the way for | Enable, Make possible | | At the forefront of | Leading, Among the first | | Harness the power of | Use, Apply | | Embark on a journey | Start, Begin | | Push the boundaries of | Expand, Challenge | | A gateway to | An entry point, A starting place | | Bridging the gap between | Connecting | | Spearhead the initiative | Lead, Start | | Capitalize on the opportunities | Take advantage of | | Navigate the complexities | Handle, Manage, Work through | | Lay the groundwork for | Prepare for, Set up | | Foster a culture of | Build, Create, Encourage | | Master the art of | Learn, Get good at, Become skilled at | | A testament to | Proof of, Evidence of | | Game-changer | (describe why it matters instead) | | Synergy | Working together, Collaboration | | Leverage | Use | | Ecosystem | System, Network, Platform | | Deep dive | Detailed look, Thorough exploration | | Move the needle | Make a difference, Show results | | Low-hanging fruit | Easy wins, Quick fixes | | Circle back | Follow up, Return to | | Touch base | Check in, Talk | | Thought leader | Expert | ### Generic Opening Phrases Never start articles or sections with these: | Avoid | Use Instead | |-------|-------------| | In today's fast-paced world | (get to the point) | | In this digital age | (be specific or remove) | | As we all know | (just state it) | | Let's delve in | Let's start, Here's how | | Let's uncover | Let's look at, Here's | | In the realm of | In, For, When it comes to | | When it comes to | For, In | | In an era where | Today, Now | ### Conclusion Phrases End with action or value, not these generic closers: | Avoid | Use Instead | |-------|-------------| | In conclusion | (just conclude) | | To sum up | (just summarize) | | To summarize | Here's what matters... | | All in all | (remove) | | At the end of the day | Ultimately, The point is | | The bottom line is | Here's what matters | ### Structural Patterns & Punctuation #### The "It's not X, it's Y" Pattern This rhetorical structure is massively overused by AI: | Avoid | Use Instead | |-------|-------------| | It's not just X, it's Y | (describe Y directly) | | It's not X - it's Y | (just explain Y) | | This isn't about X, it's about Y | (focus on Y from the start) | | It's less about X and more about Y | Y matters more than X | | It's not merely X, but Y | (just state Y) | #### Em Dash Ban Do not use em dashes at all. Zero per article. Use commas, periods, colons, parentheses, or conjunctions instead. **Replace em dashes with:** - Commas for parenthetical asides - Periods to break into separate sentences - Colons before explanations or lists - Parentheses for clarifying details - "and", "but", "because", "which" for connecting clauses #### Bolded Keywords Ban Do not bold random keywords inside body paragraphs for emphasis or SEO. The pattern of bolding "AI marketing" or "small business" or "ownership" mid-sentence is a tell that the writer is trying to signal a target keyword to a search engine rather than communicate to a reader. It also fragments the reading rhythm and looks unprofessional. **Bold is acceptable for:** - Section headings (H2, H3, H4) where bold is part of the structural style - The label portion of a list item, when the list is a definition pattern (e.g., `**Tier 1, Universal Discovery:** robots.txt, sitemap, llms.txt...`) - A single short pull-quote or stat callout, used sparingly (no more than one or two per article) **Bold is not acceptable for:** - Highlighting a keyword inside a paragraph - Emphasizing a brand term every time it appears - "SEO bolding" of phrases the writer wants to rank for - Marketing-speak emphasis like **revolutionary** or **game-changing** If a sentence needs emphasis, restructure it so the emphasis falls naturally on the right word, or use a separate sentence to call out the point. --- ## AI Tool Directive When using AI to generate content, include this directive: > Write founder to founder. The brand is lilAgents and the line is "Growth you actually own." The archetype is Outlaw plus Sage: willing to name what's broken about how legacy agencies operate, but always from a position of 15+ years of hands-on experience. Use no em dashes. Do not bold keywords inside body paragraphs. Do not use the "It's not X, it's Y" rhetorical pattern. Vary sentence structure. Avoid the following overused words and phrases: Indeed, Furthermore, However, Notably, Therefore, Additionally, In terms of, Significantly, It is worth noting, In conclusion, Consequently, Thus, Moreover, Subsequently, Accordingly, Unlock the potential of, Unleash the power of, Delve into the world of, Pave the way for, At the forefront of, Harness the power of, Embark on a journey, Push the boundaries of, A gateway to, Bridging the gap between, Spearhead the initiative, Capitalize on the opportunities, Navigate the complexities, Lay the groundwork for, Foster a culture of, It's important to note that, It's worth mentioning that, Let's delve in, Let's uncover, The reality is, The truth is. --- *Last updated: May 7, 2026* --- # FILE: style-guide.md # Visual Style Guide > This document provides design guidelines for maintaining consistent visual styling across the lilAgents website. Use these standards when creating new pages or components. ## Typography System ### Heading Hierarchy All headings follow a standardized scale for consistent visual hierarchy across the site. | Element | Tailwind Classes | Rendered Size | Usage | |---------|------------------|---------------|-------| | **H1** | `text-3xl sm:text-4xl font-bold` | max 36px | Page titles only. One per page. | | **H2** | `text-2xl sm:text-3xl font-semibold` | max 30px | Section headings | | **H3** | `text-lg font-semibold` | 18px | Card titles, subsections | | **H4** | `text-lg font-semibold` | 18px | Smaller headings where needed | ### Blog Content Typography (blog.css) For Markdown-rendered blog content, use proportional sizes: ```css h1 { font-size: 2rem; font-weight: 700; } /* 32px */ h2 { font-size: 1.75rem; font-weight: 600; } /* 28px */ h3 { font-size: 1.25rem; font-weight: 600; } /* 20px */ h4 { font-size: 1.125rem; font-weight: 600; } /* 18px */ ``` ### Design Rationale Smaller headings create: - Better balance with content - Modern, clean aesthetic - Clear visual hierarchy without overwhelming users - Improved readability on mobile devices --- ## Color System ### Background Alternation Sections should alternate between light and dark backgrounds for visual separation. | Background Type | Light Mode | Dark Mode | |-----------------|------------|-----------| | **Primary** | `bg-white` | `dark:bg-dark` | | **Secondary** | `bg-gray-1` | `dark:bg-dark-2` | | **Accent (CTA)** | `bg-primary` | `bg-primary` | ### Alternation Pattern When building pages, follow this pattern: 1. Hero section: `bg-white dark:bg-dark` or themed (e.g., hero gradient) 2. First content section: `bg-gray-1 dark:bg-dark-2` 3. Second content section: `bg-white dark:bg-dark` 4. Continue alternating... 5. CTA section: `bg-primary` (accent color) 6. Final section: `bg-white dark:bg-dark` ### Conditional Backgrounds When sections may be conditionally rendered (like video testimonials), use dynamic classes: ```astro
``` This ensures proper alternation regardless of which sections are visible. --- ## Component Patterns ### Section Headers Standard section header pattern: ```astro
Section Label

Section Title

Section description text.

``` ### Cards with Hover Animation When cards have hover animations that translate upward, ensure the parent container allows overflow: ```astro
``` The `pt-4` padding prevents clipping when cards translate upward on hover. ### CTA Sections Standard CTA section pattern: ```astro

CTA Headline

Supporting text.

Button Text
``` --- ## Case Study Template ### Section Order Case study pages follow this structure: 1. **Hero** - Title, client info, cover image 2. **Video Testimonial** (optional) - YouTube embed 3. **Challenge** - Problem statement with numbered points 4. **Solution** - What we did with icon cards 5. **Results** - Metrics grid and outcome cards 6. **Quote** - Pull quote testimonial (bg-primary) 7. **Services Used** - Tag-style badges 8. **More Case Studies** - Link to all case studies 9. **CTA** - Final call to action 10. **TaglinePattern** - Footer pattern ### Conditional Video Handling The case study template handles pages with and without video testimonials: ```astro {caseStudy.hasVideo && (
)}
``` This ensures proper background alternation whether or not the video section is rendered. --- ## Spacing Standards ### Section Padding | Screen Size | Vertical Padding | |-------------|------------------| | Mobile | `py-16` (64px) | | Desktop | `lg:py-24` (96px) | ### Container Max-Widths | Content Type | Max Width | |--------------|-----------| | Centered text content | `max-w-[570px]` | | Section descriptions | `max-w-2xl` (672px) | | Page header content | `max-w-[700px]` | | Full content area | `max-w-[800px]` | --- ## Icon Usage ### FontAwesome Icons Use FontAwesome icons for common UI elements: ```html ``` ### SVG Icons For custom icons or when FontAwesome doesn't have what you need, use inline SVGs with `currentColor`: ```html ``` --- ## Responsive Breakpoints | Breakpoint | Prefix | Screen Width | |------------|--------|--------------| | Mobile (default) | none | < 640px | | Small | `sm:` | >= 640px | | Medium | `md:` | >= 768px | | Large | `lg:` | >= 1024px | | Extra Large | `xl:` | >= 1280px | ### Common Responsive Patterns ```astro class="text-2xl sm:text-3xl" class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3" class="flex flex-col lg:flex-row" class="hidden lg:block" class="block lg:hidden" ``` --- *Last updated: December 23, 2025*