@mars-stack/core 0.4.0

package/cursor/skills/mars-build-landing-page/SKILL.md

@@ -0,0 +1,248 @@
+# Skill: Build a Landing Page
+
+Create a marketing landing page with hero, features, CTA sections using MARS design system tokens.
+
+## When to Use
+
+Use this skill when the user asks to build a landing page, marketing page, home page, or public-facing product page.
+
+## Architecture
+
+Landing pages are server components (no `'use client'`) for optimal SEO and performance. They live in the public route group.
+
+## Directory
+
+```
+src/app/(public)/page.tsx           # Home landing page
+src/app/(public)/pricing/page.tsx   # Pricing page
+src/app/(public)/about/page.tsx     # About page
+```
+
+## Template: Full Landing Page
+
+```tsx
+import { Button, LinkButton, H1, H2, Paragraph } from '@mars-stack/ui';
+import { appConfig } from '@/config/app.config';
+import type { Metadata } from 'next';
+
+export const metadata: Metadata = {
+  title: `${appConfig.name} - ${appConfig.tagline}`,
+  description: appConfig.description,
+};
+
+export default function HomePage() {
+  return (
+    <main>
+      <HeroSection />
+      <FeaturesSection />
+      <CTASection />
+    </main>
+  );
+}
+
+function HeroSection() {
+  return (
+    <section className="relative overflow-hidden bg-surface-background px-4 py-24 sm:py-32">
+      <div className="mx-auto max-w-4xl text-center">
+        <h1 className="text-4xl font-bold tracking-tight text-text-primary sm:text-6xl">
+          {appConfig.tagline}
+        </h1>
+        <p className="mx-auto mt-6 max-w-2xl text-lg leading-8 text-text-secondary">
+          {appConfig.description}
+        </p>
+        <div className="mt-10 flex items-center justify-center gap-4">
+          <LinkButton href="/register" size="lg">
+            Get Started Free
+          </LinkButton>
+          <LinkButton href="#features" variant="secondary" size="lg">
+            Learn More
+          </LinkButton>
+        </div>
+      </div>
+    </section>
+  );
+}
+
+function FeaturesSection() {
+  const features = [
+    {
+      title: 'Lightning Fast',
+      description: 'Built on Next.js 15 with Turbopack for instant feedback during development.',
+      icon: '⚡',
+    },
+    {
+      title: 'Secure by Default',
+      description: 'Authentication, CSRF protection, rate limiting, and input validation out of the box.',
+      icon: '🔒',
+    },
+    {
+      title: 'Beautiful UI',
+      description: 'A design token system that ensures consistency across every component.',
+      icon: '🎨',
+    },
+  ];
+
+  return (
+    <section id="features" className="bg-surface-card px-4 py-24">
+      <div className="mx-auto max-w-6xl">
+        <div className="text-center">
+          <H2>Everything you need</H2>
+          <Paragraph className="mx-auto mt-4 max-w-2xl text-text-secondary">
+            All the tools and infrastructure to build and ship your product.
+          </Paragraph>
+        </div>
+        <div className="mt-16 grid grid-cols-1 gap-8 sm:grid-cols-2 lg:grid-cols-3">
+          {features.map((feature) => (
+            <div
+              key={feature.title}
+              className="rounded-xl border border-border-default bg-surface-background p-6"
+            >
+              <div className="mb-4 text-3xl">{feature.icon}</div>
+              <h3 className="text-lg font-semibold text-text-primary">{feature.title}</h3>
+              <p className="mt-2 text-text-secondary">{feature.description}</p>
+            </div>
+          ))}
+        </div>
+      </div>
+    </section>
+  );
+}
+
+function CTASection() {
+  return (
+    <section className="bg-brand-primary px-4 py-24">
+      <div className="mx-auto max-w-4xl text-center">
+        <h2 className="text-3xl font-bold text-text-on-brand sm:text-4xl">
+          Ready to get started?
+        </h2>
+        <p className="mx-auto mt-4 max-w-xl text-lg text-text-on-brand/80">
+          Create your account in 30 seconds. No credit card required.
+        </p>
+        <div className="mt-8">
+          <LinkButton
+            href="/register"
+            variant="secondary"
+            size="lg"
+            className="bg-white text-brand-primary hover:bg-white/90"
+          >
+            Start Building
+          </LinkButton>
+        </div>
+      </div>
+    </section>
+  );
+}
+```
+
+## Common Sections
+
+### Social Proof / Logos
+
+```tsx
+function LogoCloud() {
+  return (
+    <section className="bg-surface-background px-4 py-16">
+      <div className="mx-auto max-w-6xl">
+        <p className="text-center text-sm font-medium text-text-muted uppercase tracking-wide">
+          Trusted by teams at
+        </p>
+        <div className="mt-8 flex flex-wrap items-center justify-center gap-8 opacity-60">
+          {/* Logo images or SVGs */}
+        </div>
+      </div>
+    </section>
+  );
+}
+```
+
+### Testimonials
+
+```tsx
+function TestimonialsSection() {
+  const testimonials = [
+    { quote: '...', author: 'Jane', role: 'CTO at Acme' },
+  ];
+
+  return (
+    <section className="bg-surface-background px-4 py-24">
+      <div className="mx-auto max-w-6xl">
+        <H2 className="text-center">What people say</H2>
+        <div className="mt-12 grid grid-cols-1 gap-8 md:grid-cols-3">
+          {testimonials.map((t, i) => (
+            <div key={i} className="rounded-xl border border-border-default bg-surface-card p-6">
+              <p className="text-text-primary italic">&ldquo;{t.quote}&rdquo;</p>
+              <div className="mt-4">
+                <p className="font-medium text-text-primary">{t.author}</p>
+                <p className="text-sm text-text-secondary">{t.role}</p>
+              </div>
+            </div>
+          ))}
+        </div>
+      </div>
+    </section>
+  );
+}
+```
+
+### Pricing Cards
+
+```tsx
+function PricingCard({ name, price, features, highlighted }: PricingCardProps) {
+  return (
+    <div className={clsx(
+      'rounded-xl border p-8',
+      highlighted
+        ? 'border-brand-primary bg-surface-card shadow-lg ring-2 ring-brand-primary'
+        : 'border-border-default bg-surface-card'
+    )}>
+      <h3 className="text-lg font-semibold text-text-primary">{name}</h3>
+      <p className="mt-4">
+        <span className="text-4xl font-bold text-text-primary">£{price}</span>
+        <span className="text-text-secondary">/month</span>
+      </p>
+      <ul className="mt-6 space-y-3">
+        {features.map((f) => (
+          <li key={f} className="flex items-center gap-2 text-text-secondary">
+            <span className="text-text-success">✓</span> {f}
+          </li>
+        ))}
+      </ul>
+      <LinkButton
+        href="/register"
+        variant={highlighted ? 'primary' : 'secondary'}
+        className="mt-8 w-full"
+      >
+        Get Started
+      </LinkButton>
+    </div>
+  );
+}
+```
+
+## SEO
+
+Landing pages should export `metadata` with:
+- `title` -- from `appConfig.name` + tagline
+- `description` -- from `appConfig.description`
+- `openGraph` -- images, type, url
+- Structured data via `JsonLd` component
+
+```tsx
+import { JsonLd } from '@mars-stack/ui';
+import { buildOrganizationJsonLd } from '@/lib/mars';
+
+// In the page:
+<JsonLd data={buildOrganizationJsonLd()} />
+```
+
+## Checklist
+
+- [ ] Server component (no `'use client'`)
+- [ ] SEO metadata exported
+- [ ] Hero with clear value proposition and CTA
+- [ ] Features section with grid layout
+- [ ] CTA section with brand background
+- [ ] All colours use semantic tokens
+- [ ] Responsive at all breakpoints
+- [ ] Uses `appConfig` for dynamic content (name, tagline, description)
+- [ ] `JsonLd` structured data included

package/cursor/skills/mars-capture-conversation-context/SKILL.md

@@ -0,0 +1,119 @@
+# Skill: Capture Conversation Context
+
+Feed decisions, discoveries, and context from the current agent conversation back into the repository so future agents can access them.
+
+## When to Use
+
+Use this skill when:
+- A significant architectural decision was made during conversation
+- A multi-step plan was executed and should be recorded
+- A bug was investigated and the root cause should be documented
+- A refactoring rationale needs to be preserved
+- The conversation is ending and produced valuable context
+
+## Prerequisites
+
+- Read `docs/design-docs/conversation-as-system-record.md` for the full design doc.
+- Read `docs/exec-plans/` to see existing plans.
+- Read `docs/QUALITY_SCORE.md` for current quality grades.
+
+## Step 1: Identify What Was Produced
+
+Review the conversation and categorise the output:
+
+| What happened | Artifact to create/update |
+|---|---|
+| Planned work and executed it | `docs/exec-plans/completed/<name>.md` |
+| Planned work (not yet executed) | `docs/exec-plans/active/<name>.md` |
+| Made an architecture decision | `docs/design-docs/<name>.md` |
+| Fixed a bug with interesting root cause | `docs/exec-plans/completed/<bug-name>.md` |
+| Discovered tech debt | `docs/exec-plans/tech-debt.md` |
+| Changed quality grades | `docs/QUALITY_SCORE.md` |
+| Updated core beliefs | `docs/design-docs/core-beliefs.md` |
+
+## Step 2: Write the Artifact
+
+### For completed execution plans
+
+Follow the `create-execution-plan` skill format but with status `Completed`. Include:
+
+```markdown
+# Execution Plan: <Title>
+
+**Status:** Completed
+**Created:** <date>
+**Completed:** <date>
+**Origin:** <Brief description of what prompted this work>
+
+## Context
+<Why this work was needed>
+
+## What Was Done
+<Summary of changes, organised by phase or area>
+
+## Key Decisions
+<Decisions made during execution, with rationale>
+
+## Discoveries
+<Anything unexpected that was found — framework quirks, bugs, constraints>
+```
+
+### For design docs
+
+```markdown
+# Design Doc: <Title>
+
+**Status:** Accepted / Proposed / Superseded
+**Created:** <date>
+
+## Problem
+<What problem does this solve?>
+
+## Decision
+<What was decided?>
+
+## Alternatives Considered
+<What else was evaluated and why it was rejected?>
+
+## Consequences
+<What are the implications of this decision?>
+```
+
+### For tech debt updates
+
+Append to the appropriate section of `docs/exec-plans/tech-debt.md`:
+
+```markdown
+| <Item> | <Location> | <Impact> | <Tracking> |
+```
+
+## Step 3: Update Cross-References
+
+1. If a new design doc was created, add it to `docs/design-docs/index.md`.
+2. If quality scores changed, update `docs/QUALITY_SCORE.md`.
+3. If an active plan was completed, move it from `active/` to `completed/`.
+4. If core beliefs were affected, update `docs/design-docs/core-beliefs.md`.
+
+## Step 4: Verify
+
+- [ ] Artifact is in the correct directory with correct status
+- [ ] Key decisions include rationale (not just what, but why)
+- [ ] Discoveries document the unexpected (things code can't convey)
+- [ ] Cross-references are updated
+- [ ] No conversation-specific noise (corrections, false starts, tone)
+
+## Anti-Patterns
+
+- **Don't dump the transcript.** Extract decisions and context, not the conversation.
+- **Don't document the obvious.** If the code diff tells the story, the artifact should explain only what the diff cannot.
+- **Don't create empty placeholders.** If the conversation didn't produce meaningful context, don't create an artifact.
+- **Don't duplicate what's in the code.** The artifact explains *why*, not *what*.
+
+## Checklist
+
+- [ ] Identified conversation output type (plan, decision, discovery, debt)
+- [ ] Created or updated the appropriate artifact
+- [ ] Included rationale for key decisions
+- [ ] Documented unexpected discoveries
+- [ ] Updated cross-references (index files, quality scores)
+- [ ] No transcript noise in the artifact