stagent 0.1.10 → 0.1.12

package/src/components/playbook/playbook-card.tsx

@@ -0,0 +1,102 @@
+"use client";
+
+import Link from "next/link";
+import { Image, ExternalLink } from "lucide-react";
+import { Badge } from "@/components/ui/badge";
+import { Card, CardHeader, CardContent } from "@/components/ui/card";
+import type { DocSection, AdoptionEntry } from "@/lib/docs/types";
+
+interface PlaybookCardProps {
+  section: DocSection;
+  adoption?: AdoptionEntry;
+}
+
+function adoptionDot(adoption?: AdoptionEntry) {
+  if (!adoption || adoption.depth === "none") {
+    return (
+      <span
+        className="h-2.5 w-2.5 rounded-full bg-muted-foreground/30"
+        title="Not explored"
+      />
+    );
+  }
+  if (adoption.depth === "light") {
+    return (
+      <span
+        className="h-2.5 w-2.5 rounded-full bg-amber-500"
+        title="Lightly explored"
+      />
+    );
+  }
+  return (
+    <span
+      className="h-2.5 w-2.5 rounded-full bg-emerald-500"
+      title="Deeply explored"
+    />
+  );
+}
+
+export function PlaybookCard({ section, adoption }: PlaybookCardProps) {
+  const isAppRoute =
+    section.route !== "cross-cutting" && section.route.startsWith("/");
+
+  return (
+    <Link
+      href={`/playbook/${section.slug}`}
+      className="block focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-xl"
+    >
+      <Card className="surface-card glass-shimmer group h-full transition-colors hover:border-border hover:bg-accent/50 rounded-xl">
+        <CardHeader className="pb-2">
+          <div className="flex items-start justify-between gap-2">
+            <div className="flex items-center gap-2 min-w-0">
+              {adoptionDot(adoption)}
+              <h3 className="text-base font-medium truncate group-hover:text-primary transition-colors">
+                {section.title}
+              </h3>
+            </div>
+            {isAppRoute ? (
+              <Badge variant="secondary" className="shrink-0 text-xs">
+                {section.route}
+              </Badge>
+            ) : (
+              <Badge variant="outline" className="shrink-0 text-xs">
+                <ExternalLink className="h-3 w-3 mr-0.5" />
+                cross-cutting
+              </Badge>
+            )}
+          </div>
+          {/* Subtitle: feature count */}
+          <p className="text-sm text-muted-foreground">
+            {section.features.length} feature
+            {section.features.length !== 1 ? "s" : ""} covered
+          </p>
+        </CardHeader>
+
+        <CardContent className="space-y-3">
+          {/* Tags */}
+          <div className="flex flex-wrap gap-1.5">
+            {section.tags.slice(0, 4).map((tag) => (
+              <Badge key={tag} variant="outline" className="text-xs font-normal">
+                {tag}
+              </Badge>
+            ))}
+            {section.tags.length > 4 && (
+              <span className="text-xs text-muted-foreground">
+                +{section.tags.length - 4}
+              </span>
+            )}
+          </div>
+
+          {/* Footer */}
+          {section.screengrabCount > 0 && (
+            <div className="flex items-center gap-1 text-xs text-muted-foreground">
+              <Image className="h-3.5 w-3.5" />
+              {section.screengrabCount} screenshot
+              {section.screengrabCount > 1 ? "s" : ""}
+            </div>
+          )}
+        </CardContent>
+      </Card>
+    </Link>
+  );
+}

package/src/components/playbook/playbook-detail-view.tsx

@@ -0,0 +1,223 @@
+"use client";
+
+import { useMemo } from "react";
+import Link from "next/link";
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+import { ArrowLeft, ArrowRight, ExternalLink } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Badge } from "@/components/ui/badge";
+import { PlaybookToc } from "./playbook-toc";
+import { RelatedDocs } from "./related-docs";
+import type { ParsedDoc, DocSection, AdoptionEntry } from "@/lib/docs/types";
+
+interface PlaybookDetailViewProps {
+  doc: ParsedDoc;
+  relatedSections: DocSection[];
+  adoption: Record<string, AdoptionEntry>;
+  allSlugs: string[];
+}
+
+/** Convert a heading text to a slug-style ID */
+function headingId(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/(^-|-$)/g, "");
+}
+
+export function PlaybookDetailView({
+  doc,
+  relatedSections,
+  adoption,
+  allSlugs,
+}: PlaybookDetailViewProps) {
+  const title =
+    (doc.frontmatter.title as string) || doc.slug.replace(/-/g, " ");
+  const tags = (doc.frontmatter.tags as string[]) || [];
+  const route = doc.frontmatter.route as string | undefined;
+  const category = doc.frontmatter.category as string | undefined;
+  const difficulty = doc.frontmatter.difficulty as string | undefined;
+
+  // Build a slug lookup from all known docs for rewriting .md links
+  const slugSet = useMemo(
+    () => new Set(allSlugs),
+    [allSlugs]
+  );
+
+  /** Custom link renderer for react-markdown */
+  function MarkdownLink({
+    href,
+    children,
+  }: {
+    href?: string;
+    children?: React.ReactNode;
+  }) {
+    if (!href) return <>{children}</>;
+
+    // Relative .md links → internal playbook links
+    if (href.includes(".md") || href.startsWith("./") || href.startsWith("../")) {
+      // Strip fragment, .md extension, and any relative path prefixes
+      const [pathPart, fragment] = href.split("#");
+      const slug = pathPart
+        .replace(/\.md$/, "")
+        .replace(/^(\.\.?\/)+/, "")          // strip leading ./ or ../
+        .replace(/^(features|journeys)\//, ""); // strip directory prefix
+      if (slugSet.has(slug)) {
+        const hashSuffix = fragment ? `#${fragment}` : "";
+        return (
+          <Link
+            href={`/playbook/${slug}${hashSuffix}`}
+            className="text-primary underline underline-offset-4 hover:text-primary/80"
+          >
+            {children}
+          </Link>
+        );
+      }
+    }
+
+    // App routes → action buttons
+    if (href.startsWith("/") && !href.startsWith("/playbook")) {
+      return (
+        <Link
+          href={href}
+          className="inline-flex items-center gap-1.5 rounded-full bg-primary px-3 py-1 text-sm font-medium text-primary-foreground no-underline hover:bg-primary/90 transition-colors"
+        >
+          {children}
+          <ArrowRight className="h-3.5 w-3.5" />
+        </Link>
+      );
+    }
+
+    // External links
+    return (
+      <a
+        href={href}
+        target="_blank"
+        rel="noopener noreferrer"
+        className="text-primary underline underline-offset-4 hover:text-primary/80 inline-flex items-center gap-0.5"
+      >
+        {children}
+        <ExternalLink className="h-3 w-3" />
+      </a>
+    );
+  }
+
+  /** Custom heading renderer that adds IDs for TOC linking */
+  function H2({ children }: { children?: React.ReactNode }) {
+    const text = typeof children === "string" ? children : String(children);
+    return <h2 id={headingId(text)}>{children}</h2>;
+  }
+
+  function H3({ children }: { children?: React.ReactNode }) {
+    const text = typeof children === "string" ? children : String(children);
+    return <h3 id={headingId(text)}>{children}</h3>;
+  }
+
+  /** Custom image renderer that resolves relative screengrab paths */
+  function MarkdownImage({
+    src,
+    alt,
+  }: {
+    src?: string;
+    alt?: string;
+  }) {
+    if (!src) return null;
+
+    // Resolve ../screengrabs/ paths to /readme/ (images live in public/readme/)
+    let resolvedSrc = src;
+    if (src.startsWith("../screengrabs/")) {
+      resolvedSrc = `/readme/${src.replace("../screengrabs/", "")}`;
+    } else if (src.startsWith("./")) {
+      resolvedSrc = `/docs/${src.replace("./", "")}`;
+    }
+
+    return (
+      <span className="block my-6">
+        <img
+          src={resolvedSrc}
+          alt={alt || ""}
+          className="rounded-xl border border-border/50 max-w-full"
+          loading="lazy"
+          onError={(e) => {
+            (e.target as HTMLImageElement).style.display = "none";
+          }}
+        />
+      </span>
+    );
+  }
+
+  return (
+    <div className="space-y-6">
+      {/* Back nav */}
+      <div className="flex items-center gap-4">
+        <Button variant="ghost" size="sm" asChild>
+          <Link href="/playbook">
+            <ArrowLeft className="h-4 w-4 mr-1" />
+            Playbook
+          </Link>
+        </Button>
+        {route && route !== "cross-cutting" && (
+          <Button variant="outline" size="sm" asChild>
+            <Link href={route}>
+              Open {title}
+              <ArrowRight className="h-3.5 w-3.5 ml-1" />
+            </Link>
+          </Button>
+        )}
+      </div>
+
+      {/* Title + meta */}
+      <div className="space-y-2">
+        <h1 className="text-3xl font-bold tracking-tight">{title}</h1>
+        <div className="flex flex-wrap items-center gap-2">
+          {category && (
+            <Badge variant="secondary" className="text-xs">
+              {category}
+            </Badge>
+          )}
+          {difficulty && (
+            <Badge variant="outline" className="text-xs">
+              {difficulty}
+            </Badge>
+          )}
+          {tags.slice(0, 6).map((tag) => (
+            <Badge key={tag} variant="outline" className="text-xs font-normal">
+              {tag}
+            </Badge>
+          ))}
+        </div>
+      </div>
+
+      {/* Content layout: TOC sidebar + prose */}
+      <div className="flex gap-8">
+        {/* TOC sidebar — hidden on mobile */}
+        <aside className="hidden lg:block w-48 shrink-0">
+          <div className="sticky top-20">
+            <PlaybookToc body={doc.body} />
+          </div>
+        </aside>
+
+        {/* Prose content */}
+        <div className="flex-1 min-w-0">
+          <div className="prose dark:prose-invert max-w-none prose-headings:scroll-mt-20 prose-img:rounded-xl prose-img:border prose-img:border-border/50">
+            <ReactMarkdown
+              remarkPlugins={[remarkGfm]}
+              components={{
+                a: MarkdownLink as never,
+                h2: H2 as never,
+                h3: H3 as never,
+                img: MarkdownImage as never,
+              }}
+            >
+              {doc.body}
+            </ReactMarkdown>
+          </div>
+
+          {/* Related docs */}
+          <RelatedDocs sections={relatedSections} adoption={adoption} />
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/playbook/playbook-homepage.tsx

@@ -0,0 +1,142 @@
+"use client";
+
+import Link from "next/link";
+import {
+  BookOpen,
+  Sparkles,
+  Rocket,
+  Crown,
+  ArrowRight,
+} from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Badge } from "@/components/ui/badge";
+import { PlaybookBrowser } from "./playbook-browser";
+import { AdoptionHeatmap } from "./adoption-heatmap";
+import type {
+  DocManifest,
+  UsageStage,
+  AdoptionEntry,
+  JourneyCompletion,
+} from "@/lib/docs/types";
+
+interface PlaybookHomepageProps {
+  manifest: DocManifest;
+  stage: UsageStage;
+  adoption: Record<string, AdoptionEntry>;
+  journeyCompletions: Record<string, JourneyCompletion>;
+  hasUpdates: boolean;
+}
+
+const stageConfig: Record<
+  UsageStage,
+  {
+    icon: typeof BookOpen;
+    title: string;
+    subtitle: string;
+    ctaLabel: string;
+    ctaSlug: string;
+  }
+> = {
+  new: {
+    icon: BookOpen,
+    title: "Welcome to Stagent",
+    subtitle:
+      "Your AI agent orchestrator. Start with the getting started guide or explore feature docs at your own pace.",
+    ctaLabel: "Getting Started",
+    ctaSlug: "getting-started",
+  },
+  early: {
+    icon: Sparkles,
+    title: "Keep Building",
+    subtitle:
+      "You've started creating tasks. Follow a guided journey to unlock more of what Stagent can do.",
+    ctaLabel: "Personal Use Guide",
+    ctaSlug: "personal-use",
+  },
+  active: {
+    icon: Rocket,
+    title: "Level Up",
+    subtitle:
+      "You're actively using Stagent. Explore advanced workflows, schedules, and multi-agent features.",
+    ctaLabel: "Power User Guide",
+    ctaSlug: "power-user",
+  },
+  power: {
+    icon: Crown,
+    title: "Master Mode",
+    subtitle:
+      "You've unlocked the full platform. Dive into cross-cutting guides and developer docs.",
+    ctaLabel: "Developer Guide",
+    ctaSlug: "developer",
+  },
+};
+
+export function PlaybookHomepage({
+  manifest,
+  stage,
+  adoption,
+  journeyCompletions,
+  hasUpdates,
+}: PlaybookHomepageProps) {
+  const config = stageConfig[stage];
+  const Icon = config.icon;
+
+  const adoptedCount = Object.values(adoption).filter(
+    (a) => a.adopted
+  ).length;
+  const totalSections = manifest.sections.length;
+
+  return (
+    <div className="space-y-8">
+      {/* Hero */}
+      <div className="surface-panel rounded-2xl p-6 md:p-8">
+        <div className="flex flex-col md:flex-row md:items-center md:justify-between gap-4">
+          <div className="flex items-start gap-4">
+            <div className="flex h-12 w-12 shrink-0 items-center justify-center rounded-xl bg-primary/10">
+              <Icon className="h-6 w-6 text-primary" />
+            </div>
+            <div className="space-y-1">
+              <div className="flex items-center gap-2">
+                <h1 className="text-3xl font-bold tracking-tight">
+                  {config.title}
+                </h1>
+                {hasUpdates && (
+                  <Badge className="bg-primary/10 text-primary text-xs">
+                    Updated
+                  </Badge>
+                )}
+              </div>
+              <p className="text-base text-muted-foreground max-w-lg">
+                {config.subtitle}
+              </p>
+              {stage !== "new" && (
+                <p className="text-sm text-muted-foreground">
+                  {adoptedCount} of {totalSections} features explored
+                </p>
+              )}
+            </div>
+          </div>
+          <Button asChild>
+            <Link href={`/playbook/${config.ctaSlug}`}>
+              {config.ctaLabel}
+              <ArrowRight className="h-4 w-4 ml-1" />
+            </Link>
+          </Button>
+        </div>
+      </div>
+
+      {/* Adoption Heatmap — shown for active/power users */}
+      {(stage === "active" || stage === "power") && (
+        <AdoptionHeatmap sections={manifest.sections} adoption={adoption} />
+      )}
+
+      {/* Full Browser */}
+      <PlaybookBrowser
+        sections={manifest.sections}
+        journeys={manifest.journeys}
+        adoption={adoption}
+        journeyCompletions={journeyCompletions}
+      />
+    </div>
+  );
+}

package/src/components/playbook/playbook-toc.tsx

@@ -0,0 +1,90 @@
+"use client";
+
+import { useEffect, useState, useRef } from "react";
+
+interface TocItem {
+  id: string;
+  text: string;
+  level: number;
+}
+
+interface PlaybookTocProps {
+  body: string;
+}
+
+/** Extract ## and ### headings from markdown body */
+function extractHeadings(body: string): TocItem[] {
+  const headingRegex = /^(#{2,3})\s+(.+)$/gm;
+  const items: TocItem[] = [];
+  let match;
+
+  while ((match = headingRegex.exec(body)) !== null) {
+    const level = match[1].length;
+    const text = match[2].trim();
+    const id = text
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/(^-|-$)/g, "");
+    items.push({ id, text, level });
+  }
+
+  return items;
+}
+
+export function PlaybookToc({ body }: PlaybookTocProps) {
+  const headings = extractHeadings(body);
+  const [activeId, setActiveId] = useState<string>("");
+  const observerRef = useRef<IntersectionObserver | null>(null);
+
+  useEffect(() => {
+    observerRef.current = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            setActiveId(entry.target.id);
+          }
+        }
+      },
+      { rootMargin: "-80px 0px -60% 0px", threshold: 0 }
+    );
+
+    const elements = headings
+      .map((h) => document.getElementById(h.id))
+      .filter(Boolean) as HTMLElement[];
+
+    for (const el of elements) {
+      observerRef.current.observe(el);
+    }
+
+    return () => observerRef.current?.disconnect();
+  }, [headings]);
+
+  if (headings.length < 2) return null;
+
+  return (
+    <nav className="space-y-1" aria-label="Table of contents">
+      <h4 className="text-sm font-semibold uppercase tracking-wider text-muted-foreground mb-2">
+        On this page
+      </h4>
+      {headings.map((h) => (
+        <a
+          key={h.id}
+          href={`#${h.id}`}
+          className={`block text-sm py-0.5 transition-colors hover:text-foreground ${
+            h.level === 3 ? "pl-3" : ""
+          } ${
+            activeId === h.id
+              ? "text-primary font-medium"
+              : "text-muted-foreground"
+          }`}
+          onClick={(e) => {
+            e.preventDefault();
+            document.getElementById(h.id)?.scrollIntoView({ behavior: "smooth" });
+          }}
+        >
+          {h.text}
+        </a>
+      ))}
+    </nav>
+  );
+}

package/src/components/playbook/playbook-updated-badge.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/** Small "Updated" dot badge for sidebar — shows when docs changed since last visit */
+export function PlaybookUpdatedBadge() {
+  const [hasUpdates, setHasUpdates] = useState(false);
+
+  useEffect(() => {
+    fetch("/api/playbook/status")
+      .then((r) => (r.ok ? r.json() : null))
+      .then((data) => {
+        if (data?.hasUpdates) setHasUpdates(true);
+      })
+      .catch(() => {});
+  }, []);
+
+  if (!hasUpdates) return null;
+
+  return (
+    <span className="ml-auto flex h-2 w-2 rounded-full bg-primary" aria-label="Updated docs available" />
+  );
+}

package/src/components/playbook/related-docs.tsx

@@ -0,0 +1,30 @@
+"use client";
+
+import { PlaybookCard } from "./playbook-card";
+import type { DocSection, AdoptionEntry } from "@/lib/docs/types";
+
+interface RelatedDocsProps {
+  sections: DocSection[];
+  adoption: Record<string, AdoptionEntry>;
+}
+
+export function RelatedDocs({ sections, adoption }: RelatedDocsProps) {
+  if (sections.length === 0) return null;
+
+  return (
+    <div className="space-y-3 pt-6 border-t border-border/50">
+      <h3 className="text-base font-medium text-muted-foreground uppercase tracking-wider">
+        Related Docs
+      </h3>
+      <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
+        {sections.map((section) => (
+          <PlaybookCard
+            key={section.slug}
+            section={section}
+            adoption={adoption[section.slug]}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}