@terra-symposium/docs 0.2.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terra-symposium/docs",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Docs workspace and Markdown site generator.",
   "repository": {
     "type": "git",
@@ -16,6 +16,7 @@
     "bin",
     "site",
     "src/components/navigation.tsx",
+    "src/components/quiz-demo-fixture.ts",
     "src/components/SiteLayout.astro",
     "src/components/NotFound.astro",
     "src/components/NotFound.tsx"
@@ -35,11 +36,7 @@
       "import": "./dist/lib/components/LocalDocsWorkspace.js"
     },
     "./site-layout.astro": "./src/components/SiteLayout.astro",
-    "./not-found.astro": "./src/components/NotFound.astro",
-    "./skills": {
-      "types": "./site/src/components/SkillsExplorer.tsx",
-      "import": "./site/src/components/SkillsExplorer.tsx"
-    }
+    "./not-found.astro": "./src/components/NotFound.astro"
   },
   "bin": {
     "terra-docs": "bin/terra-docs.mjs"
@@ -47,8 +44,8 @@
   "scripts": {
     "dev": "terra-quality-dev -- vite --host 127.0.0.1 --open",
     "docs:dev": "pnpm build && node bin/terra-docs.mjs dev --title 'Docs'",
-    "docs:build": "pnpm build && node bin/terra-docs.mjs build --title 'Docs'",
-    "docs:preview": "pnpm docs:build && node bin/terra-docs.mjs preview --title 'Docs'",
+    "docs:build": "pnpm build && node bin/terra-docs.mjs build --title 'Docs' --out dist/docs",
+    "docs:preview": "pnpm docs:build && node bin/terra-docs.mjs preview --title 'Docs' --out dist/docs",
     "dev:library": "tsc --watch",
     "prebuild": "pnpm exec terra-quality error-boundaries --all",
     "build": "rm -rf dist/lib && tsc && tailwindcss --postcss tailwind.postcss.config.cjs -c tailwind.docs.config.mjs -i src/styles/style.css -o dist/lib/style.css --minify && tailwindcss --postcss tailwind.postcss.config.cjs -c tailwind.docs.config.mjs -i src/styles/workspace.css -o dist/lib/workspace.css --minify && node scripts/copy-runtime.mjs",
@@ -71,7 +68,6 @@
     "@playwright/test": "^1.64.1",
     "@terra-symposium/standards-quality": "2.1.3",
     "@terra-symposium/standards-reporting": "0.6.2",
-    "@types/katex": "^0.16.8",
     "@types/node": "^24.19.2",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
@@ -80,6 +76,7 @@
     "eslint": "10.13.0",
     "globals": "^16.5.0",
     "husky": "^9.1.7",
+    "knip": "^6.44.1",
     "postcss": "8.5.31",
     "postcss-import": "15.1.0",
     "prettier": "3.9.10",
@@ -104,14 +101,13 @@
     "@lexical/rich-text": "^0.35.0",
     "@portabletext/editor": "7.9.0",
     "@radix-ui/react-popover": "^1.1.15",
-    "@radix-ui/react-select": "2.4.1",
     "@terra-symposium/standards-error-boundaries": "0.1.2",
     "@terra-symposium/styling": "0.1.34",
-    "bezier-easing": "2.1.0",
-    "@xstate/react": "6.1.0",
     "@uiw/codemirror-theme-github": "^4.25.9",
+    "@xstate/react": "6.1.0",
     "@xyflow/react": "^12.3.6",
     "astro": "^7.4.2",
+    "bezier-easing": "2.1.0",
     "html-to-image": "1.11.11",
     "jszip": "^3.10.1",
     "katex": "^0.19.1",

package/site/docs-content-plugin.mjs

@@ -8,7 +8,10 @@ function publicRoute(file, docsRoot, base) {
     .split(sep)
     .join('/')
     .replace(/\.(?:md|mdx)$/i, '');
-  const route = path.replace(/(?:^|\/)index$/i, '').replace(/^\/+|\/+$/g, '');
+  const route = path
+    .replace(/(?:^|\/)SKILL$/i, '')
+    .replace(/(?:^|\/)index$/i, '')
+    .replace(/^\/+|\/+$/g, '');
   return `${base}${route ? `${route}/` : ''}`;
 }
 

package/site/src/components/QuizDemo.tsx

@@ -0,0 +1,62 @@
+import { DocsSiteIsland } from './DocsSiteIsland.js';
+import type { DocsSection } from '../../../dist/lib/lib/workspace-types.js';
+import type { DocsQuizConfig, DocsQuizGenerationInput } from '../../../dist/lib/components/quiz.js';
+import { quizDemoLeaf, quizDemoResponse } from '../../../src/components/quiz-demo-fixture.js';
+
+const markdown = quizDemoLeaf.markdown;
+const visibleLeafText = markdown.split('\n\n', 1)[0] ?? markdown;
+
+const sections: DocsSection[] = [
+  {
+    id: 'course',
+    title: 'Course',
+    groups: [
+      {
+        id: 'lessons',
+        title: 'Lessons',
+        leaves: [
+          {
+            id: quizDemoLeaf.id,
+            title: quizDemoLeaf.title,
+            href: '/quiz-demo/',
+            description: 'The routing leaf shared with the quiz browser tests.',
+          },
+        ],
+      },
+    ],
+  },
+];
+
+function genDemoQuiz(input: DocsQuizGenerationInput): Promise<unknown> {
+  return Promise.resolve({
+    title: `${quizDemoResponse.title} · sample`,
+    questions: Array.from({ length: input.count }, (_, i) => {
+      const type = input.types[i % input.types.length];
+      const question =
+        quizDemoResponse.questions.find((candidate) => candidate.type === type) ??
+        quizDemoResponse.questions[0];
+      return { ...question };
+    }),
+  });
+}
+
+const quiz: DocsQuizConfig = { toolbar: true, generate: genDemoQuiz };
+
+/** A package-safe interactive demo for the host-configurable leaf quiz flow. */
+export function QuizDemo() {
+  return (
+    <DocsSiteIsland
+      title="Docs quiz demo"
+      description="The published Docs workspace with sample leaf quiz generation."
+      hue={145}
+      sections={sections}
+      currentPath="/quiz-demo/"
+      rootPath="/quiz-demo/"
+      staticContent
+      markdown={markdown}
+      renderContent={<p className="leading-7">{visibleLeafText}</p>}
+      quiz={quiz}
+      searchBase="/"
+    />
+  );
+}

package/site/src/lib/catalog.ts

@@ -72,10 +72,17 @@ const sources = import.meta.glob<string>('/docs/**/*.{md,mdx}', {
   eager: true,
 });
 const base = import.meta.env.BASE_URL;
+const includeAgents = import.meta.env.PUBLIC_TERRA_DOCS_INCLUDE_AGENTS !== 'false';
 const routes = new Map<string, string>();
 /** Visible Docs pages sorted by configured sidebar order and source path. */
 export const sitePages: SitePage[] = Object.entries(modules)
+  .filter(([file]) => includeAgents || !file.startsWith('/docs/agents/'))
   .map(([file, module]) => {
+    const relativeFile = file.replace(/^\/docs\//, '');
+    const isRootIndex = ['index.md', 'index.mdx'].includes(relativeFile.toLowerCase());
+    if (!isRootIndex && !relativeFile.includes('/')) {
+      throw new Error(`Markdown pages must be grouped in folders directly under docs/: ${file}`);
+    }
     const slug = routeForFile(file);
     const previous = routes.get(slug);
     if (previous) throw new Error(`Duplicate Docs route "${slug || '/'}": ${previous} and ${file}`);
@@ -131,7 +138,10 @@ function titleFromSource(source: string, slug: string): string {
  */
 function routeForFile(file: string): string {
   const relative = file.replace(/^\/?docs\//, '').replace(/\.(?:md|mdx)$/i, '');
-  return relative.replace(/(?:^|\/)index$/i, '').replace(G_CLASS_2(), '');
+  return relative
+    .replace(/(?:^|\/)SKILL$/i, '')
+    .replace(/(?:^|\/)index$/i, '')
+    .replace(G_CLASS_2(), '');
 }
 
 /**

package/site/src/pages/[...slug].astro

@@ -15,11 +15,10 @@ export function getStaticPaths() {
 
 const { slug = '' } = Astro.props;
 const page = pageForSlug(slug);
-const PageContent = page?.content;
 const currentPath = pageHref(slug, base);
 ---
 
-{page && PageContent ? (
+{page ? (
 	<html lang="en">
 		<head>
 			<meta charset="utf-8" />
@@ -37,14 +36,9 @@ const currentPath = pageHref(slug, base);
 				nodes={siteNavigation}
 				currentPath={currentPath}
 				rootPath={pageHref('', base)}
+				markdown={page.markdown}
 				searchBase={base}
-			>
-				<div class="terra-docs-page-content"><PageContent /></div>
-			</DocsSiteLayout>
+			/>
 		</body>
 	</html>
 ) : null}
-
-<style is:global>
-	.terra-docs-page-content { max-width: 100%; }
-</style>

package/site/src/pages/quiz-demo.astro

@@ -0,0 +1,50 @@
+---
+import { QuizDemo } from '../components/QuizDemo.js';
+import '@terra-symposium/docs/style.css';
+---
+<!doctype html>
+<html lang="en" class="light">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<meta name="description" content="Try the shared Docs leaf quiz flow with the Playwright workspace fixture." />
+		<title>Leaf quiz demo · Docs</title>
+	</head>
+	<body>
+		<header class="demo-intro">
+			<p>Docs component demo</p>
+			<h1>Generate a quiz from a leaf</h1>
+			<p>Select a leaf, then choose <strong>Generate quiz</strong>. This fixture returns clearly marked sample questions and never sends content to an AI service.</p>
+		</header>
+		<QuizDemo client:load />
+	</body>
+</html>
+
+<style>
+	.demo-intro {
+		margin-left: 22rem;
+		padding: 1.25rem clamp(1rem, 4vw, 3rem);
+		background: #f7f4fb;
+		color: #24172f;
+	}
+	.demo-intro > p:first-child {
+		margin: 0 0 0.35rem;
+		font-size: 0.75rem;
+		font-weight: 700;
+		letter-spacing: 0.08em;
+		text-transform: uppercase;
+	}
+	.demo-intro h1 {
+		margin: 0;
+		font-size: clamp(1.25rem, 2.5vw, 1.8rem);
+	}
+	.demo-intro > p:last-child {
+		margin: 0.35rem 0 0;
+		font-size: 0.9rem;
+	}
+	@media (max-width: 767px) {
+		.demo-intro {
+			margin-left: 0;
+		}
+	}
+</style>

package/src/components/navigation.tsx

@@ -27,8 +27,8 @@ export function DocsNavigation({
   const style = { '--docs-accent': `rgb(${accent.light[8]})` } as CSSProperties;
   const render = (items: DocsNavNode[]): JSX.Element => (
     <ul className="terra-docs-nav-list">
-      {items.map((node, index) => (
-        <li key={`${node.href ?? node.title}-${index}`}>
+      {items.map((node, i) => (
+        <li key={`${node.href ?? node.title}-${i}`}>
           {node.href ? (
             <a href={node.href} aria-current={node.href === currentPath ? 'page' : undefined}>
               {node.title}

package/src/components/quiz-demo-fixture.ts

@@ -0,0 +1,23 @@
+/** Shared quiz leaf data used by the public demo and its Playwright fixture. */
+export const quizDemoLeaf = {
+  id: 'quiz-leaf',
+  path: 'content/course/quiz-leaf/index.md',
+  title: 'Course Leaf',
+  markdown:
+    'Leaf source: routing sends packets between networks.\n\n:::terra-docs quiz\n_type: quiz\n:::',
+};
+
+/** Stable sample response for review, run, and score coverage. */
+export const quizDemoResponse = {
+  title: 'Routing quiz',
+  questions: [
+    {
+      type: 'multipleChoice',
+      prompt: 'What does a router do?',
+      opts: ['Routes packets', 'Stores files'],
+      answer: 'Routes packets',
+      explanation: 'It forwards packets between networks.',
+    },
+    { type: 'keyword', prompt: 'What does it forward?', answers: ['packets'] },
+  ],
+} as const;

package/bin/generate-skills.mjs

@@ -1,186 +0,0 @@
-#!/usr/bin/env node
-
-/*//////////////////////////////////////////////////
-IMPORTS
-//////////////////////////////////////////////////*/
-
-// API
-import { dirname, join, relative, resolve, sep } from 'node:path';
-import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
-import { parse } from 'yaml';
-
-/*//////////////////////////////////////////////////
-CONFIG
-//////////////////////////////////////////////////*/
-
-const ignoredDirs = new Set([
-  '.astro',
-  '.cache',
-  '.git',
-  '.next',
-  '.nuxt',
-  '.output',
-  '.svelte-kit',
-  '.turbo',
-  '.vite',
-  '.vercel',
-  '.wrangler',
-  'build',
-  'coverage',
-  'dist',
-  'docs-dist',
-  'node_modules',
-  'target',
-  'vendor',
-]);
-
-/*//////////////////////////////////////////////////
-HELPERS
-//////////////////////////////////////////////////*/
-
-/**
- * Finds skill instruction files beneath a directory, skipping generated and dependency folders.
- *
- * @param dir Directory whose descendants should be searched.
- * @param files Accumulator shared by recursive calls.
- *
- * @return Paths to the discovered `SKILL.md` files.
- */
-async function findSkillFiles(dir, files = []) {
-  const entries = await readdir(dir, { withFileTypes: true });
-  for (const entry of entries) {
-    if (entry.isDirectory() && ignoredDirs.has(entry.name)) continue;
-    const path = join(dir, entry.name);
-    if (entry.isDirectory()) await findSkillFiles(path, files);
-    else if (entry.isFile() && entry.name === 'SKILL.md') files.push(path);
-  }
-  return files;
-}
-
-/**
- * Separates a skill document's Markdown body from its optional YAML frontmatter.
- *
- * @param source Complete skill document contents.
- *
- * @return Parsed metadata and body, plus a validation issue when YAML parsing fails.
- */
-function splitFrontmatter(source) {
-  const match = /^---\s*\n([\s\S]*?)\n---\s*\n?/.exec(source);
-  if (!match) return { body: source.trim(), metadata: {}, metadataIssue: undefined };
-  try {
-    const metadata = parse(match[1]);
-    return {
-      body: source.slice(match[0].length).trim(),
-      metadata:
-        metadata && typeof metadata === 'object' && !Array.isArray(metadata) ? metadata : {},
-      metadataIssue: undefined,
-    };
-  } catch (err) {
-    return {
-      body: source.slice(match[0].length).trim(),
-      metadata: {},
-      metadataIssue: err instanceof Error ? err.message : String(err),
-    };
-  }
-}
-
-/**
- * Resolves a skill's display scope and directory from its repository-relative path.
- *
- * @param root Repository root used to make the skill path relative.
- * @param path Absolute path of the skill instruction file.
- *
- * @return Directory and scope labels for the generated index entry.
- */
-function skillLocation(root, path) {
-  const segments = relative(root, path).split(sep);
-  const skillRootIndex = segments.findIndex(
-    (segment, i) => (segment === '.agents' || segment === '.codex') && segments[i + 1] === 'skills',
-  );
-  if (skillRootIndex >= 0) {
-    const scope = segments.slice(0, skillRootIndex).join('/') || 'repository';
-    const dir = segments.slice(skillRootIndex + 2, -1).join('/') || 'root';
-    return { directory: dir, scope };
-  }
-  return { directory: segments.slice(0, -1).join('/') || 'root', scope: 'repository' };
-}
-
-/**
- * Derives a fallback description from the first prose paragraph in a skill document.
- *
- * @param body Markdown body with frontmatter removed.
- *
- * @return The first non-heading paragraph, or an empty string when none exists.
- */
-function fallbackDescription(body) {
-  return (
-    body
-      .replace(/^\s*#.+\n/, '')
-      .split(/\n\s*\n/)
-      .map((paragraph) => paragraph.replace(/\s+/g, ' ').trim())
-      .find((paragraph) => paragraph && !paragraph.startsWith('#')) ?? ''
-  );
-}
-
-/**
- * Converts a directory or skill name into a title-style label.
- *
- * @param value Slug containing words separated by hyphens or underscores.
- *
- * @return A human-readable label with each word capitalized.
- */
-function humanize(value) {
-  return value.replace(/[-_]+/g, ' ').replace(/\b\p{L}/gu, (letter) => letter.toUpperCase());
-}
-
-/**
- * Builds a sorted index of repository skills and writes it as JSON.
- *
- * @param repoRoot Repository root whose `.agents` and `.codex` skill trees are scanned.
- * @param outputPath Destination file for the generated skill index.
- *
- * @return The indexed skills, including their parsed metadata and Markdown bodies.
- */
-export async function generateSkillsIndex(repoRoot, outputPath) {
-  const root = resolve(repoRoot);
-  const files = await findSkillFiles(root);
-  const skills = await Promise.all(
-    files.map(async (path) => {
-      const source = await readFile(path, 'utf8');
-      const { body, metadata, metadataIssue } = splitFrontmatter(source);
-      const location = skillLocation(root, path);
-      const dirName = location.directory.split('/').at(-1) ?? 'skill';
-      const name = typeof metadata.name === 'string' ? metadata.name.trim() : dirName;
-      const title = /^#\s+(.+?)\s*#*\s*$/m.exec(body)?.[1]?.trim() ?? humanize(name);
-      const description =
-        typeof metadata.description === 'string'
-          ? metadata.description.trim()
-          : fallbackDescription(body);
-      return {
-        body,
-        description,
-        directory: location.directory,
-        metadata,
-        ...(metadataIssue ? { metadataIssue } : {}),
-        name,
-        scope: location.scope,
-        sourcePath: relative(root, path).split(sep).join('/'),
-        title,
-      };
-    }),
-  );
-  skills.sort((first, second) =>
-    `${first.scope}/${first.directory}/${first.name}`.localeCompare(
-      `${second.scope}/${second.directory}/${second.name}`,
-    ),
-  );
-  await mkdir(dirname(outputPath), { recursive: true });
-  await writeFile(outputPath, `${JSON.stringify(skills, null, 2)}\n`);
-  return skills;
-}
-if (process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname)) {
-  const root = resolve(process.argv[2] ?? process.cwd());
-  const outputPath = resolve(process.argv[3] ?? join(root, 'dist/cache/skills.generated.json'));
-  const skills = await generateSkillsIndex(root, outputPath);
-  console.log(`Indexed ${skills.length} skills from ${root}`);
-}