@terra-symposium/docs 0.1.74 → 0.1.76

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terra-symposium/docs",
-  "version": "0.1.74",
+  "version": "0.1.76",
   "description": "Terra Docs workspace and Markdown site generator.",
   "repository": {
     "type": "git",
@@ -35,7 +35,11 @@
       "import": "./lib-dist/components/LocalDocsWorkspace.js"
     },
     "./site-layout.astro": "./src/components/SiteLayout.astro",
-    "./not-found.astro": "./src/components/NotFound.astro"
+    "./not-found.astro": "./src/components/NotFound.astro",
+    "./skills": {
+      "types": "./site/src/components/SkillsExplorer.tsx",
+      "import": "./site/src/components/SkillsExplorer.tsx"
+    }
   },
   "bin": {
     "terra-docs": "bin/terra-docs.mjs"

package/site/astro.config.mjs

@@ -13,7 +13,7 @@ const packageRoot = fileURLToPath(new URL('../', import.meta.url));
 const requireFromPackage = createRequire(import.meta.url);
 const projectRoot = process.env.TERRA_DOCS_ROOT ?? process.cwd();
 const publicDir = resolve(projectRoot, '.terra-docs/public');
-const outDir = resolve(projectRoot, process.env.TERRA_DOCS_OUT ?? 'docs-dist');
+const outDir = resolve(projectRoot, process.env.TERRA_DOCS_OUT ?? 'dist/docs');
 const site = process.env.TERRA_DOCS_SITE;
 const base = process.env.TERRA_DOCS_BASE ?? '/';
 const projectManifest = (() => {

package/site/src/components/DocsSiteSearch.tsx

@@ -34,6 +34,7 @@ export function DocsSiteSearch({ base = '/' }: Props) {
   };
 
   useEffect(() => {
+    const onOpenSearch = () => open();
     const onKeyDown = (event: KeyboardEvent) => {
       if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') {
         event.preventDefault();
@@ -46,8 +47,12 @@ export function DocsSiteSearch({ base = '/' }: Props) {
         open();
       }
     };
+    document.addEventListener('docs:open-search', onOpenSearch);
     document.addEventListener('keydown', onKeyDown);
-    return () => document.removeEventListener('keydown', onKeyDown);
+    return () => {
+      document.removeEventListener('docs:open-search', onOpenSearch);
+      document.removeEventListener('keydown', onKeyDown);
+    };
   }, []);
 
   useEffect(() => {
@@ -85,16 +90,6 @@ export function DocsSiteSearch({ base = '/' }: Props) {
 
   return (
     <div className="terra-docs-search">
-      <button
-        className="terra-docs-search-trigger"
-        type="button"
-        onClick={open}
-        aria-label="Search documentation"
-      >
-        <span aria-hidden="true">⌕</span>
-        <span>Search docs</span>
-        <kbd>⌘ K</kbd>
-      </button>
       <dialog className="terra-docs-search-dialog" ref={dialog} onClose={() => setQuery('')}>
         <div className="terra-docs-search-panel">
           <label className="terra-docs-search-input-row">

package/site/src/components/SkillsExplorer.tsx

@@ -0,0 +1,157 @@
+import { useMemo, useState } from 'react';
+import '../styles/skills-explorer.css';
+
+export type SkillRecord = {
+  body: string;
+  description: string;
+  directory: string;
+  metadata: Record<string, unknown>;
+  metadataIssue?: string;
+  name: string;
+  scope: string;
+  sourcePath: string;
+  title: string;
+};
+
+function metadataValue(value: unknown) {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  return JSON.stringify(value);
+}
+
+function plural(count: number, singular: string) {
+  return `${count} ${singular}${count === 1 ? '' : 's'}`;
+}
+
+export function SkillsExplorer({ skills }: { skills: SkillRecord[] }) {
+  const [query, setQuery] = useState('');
+  const [activePath, setActivePath] = useState(skills[0]?.sourcePath ?? '');
+  const filteredSkills = useMemo(() => {
+    const normalizedQuery = query.trim().toLocaleLowerCase();
+    if (!normalizedQuery) return skills;
+    return skills.filter((skill) =>
+      [
+        skill.name,
+        skill.title,
+        skill.description,
+        skill.directory,
+        skill.scope,
+        skill.sourcePath,
+        JSON.stringify(skill.metadata),
+        skill.body,
+      ]
+        .join('\n')
+        .toLocaleLowerCase()
+        .includes(normalizedQuery),
+    );
+  }, [query, skills]);
+  const selectedSkill =
+    filteredSkills.find((skill) => skill.sourcePath === activePath) ?? filteredSkills[0] ?? null;
+  const groups = useMemo(() => {
+    const byScope = new Map<string, SkillRecord[]>();
+    for (const skill of filteredSkills) {
+      const entries = byScope.get(skill.scope) ?? [];
+      entries.push(skill);
+      byScope.set(skill.scope, entries);
+    }
+    return [...byScope.entries()];
+  }, [filteredSkills]);
+  const metadataEntries = selectedSkill
+    ? Object.entries(selectedSkill.metadata).filter(([key]) => !['name', 'description'].includes(key))
+    : [];
+
+  return (
+    <section aria-label="Repository skills" className="docs-skills">
+      <header className="docs-skills__header">
+        <div>
+          <p className="docs-skills__eyebrow">Repository inventory</p>
+          <h2>Skills</h2>
+          <p>Browse the workflows and guidance files included in this repository.</p>
+        </div>
+        <div aria-live="polite" className="docs-skills__summary">
+          <strong>{skills.length}</strong>
+          <span>{plural(skills.length, 'skill')} indexed</span>
+        </div>
+      </header>
+
+      {skills.length ? (
+        <div className="docs-skills__layout">
+          <nav aria-label="Available skills" className="docs-skills__index">
+            <label className="docs-skills__filter">
+              <span>Filter skills</span>
+              <input
+                onChange={(event) => setQuery(event.currentTarget.value)}
+                placeholder="Name, topic, or text"
+                type="search"
+                value={query}
+              />
+            </label>
+            <p aria-live="polite" className="docs-skills__count">
+              Showing {filteredSkills.length} of {skills.length}
+            </p>
+            {groups.length ? (
+              groups.map(([scope, entries]) => (
+                <section aria-label={scope} className="docs-skills__group" key={scope}>
+                  <h3>{scope}</h3>
+                  <ul>
+                    {entries.map((skill) => (
+                      <li key={skill.sourcePath}>
+                        <button
+                          aria-current={selectedSkill?.sourcePath === skill.sourcePath ? 'true' : undefined}
+                          className="docs-skills__item"
+                          onClick={() => setActivePath(skill.sourcePath)}
+                          type="button"
+                        >
+                          <span className="docs-skills__item-title">{skill.title}</span>
+                          <span className="docs-skills__item-description">{skill.description || skill.name}</span>
+                          <span className="docs-skills__item-path">{skill.directory}</span>
+                        </button>
+                      </li>
+                    ))}
+                  </ul>
+                </section>
+              ))
+            ) : (
+              <p className="docs-skills__empty">No skills match “{query}”.</p>
+            )}
+          </nav>
+
+          {selectedSkill ? (
+            <article aria-live="polite" className="docs-skills__detail">
+              <header>
+                <p className="docs-skills__eyebrow">{selectedSkill.scope}</p>
+                <h3>{selectedSkill.title}</h3>
+                <p className="docs-skills__description">{selectedSkill.description}</p>
+                <p className="docs-skills__source-path">{selectedSkill.sourcePath}</p>
+              </header>
+              {metadataEntries.length ? (
+                <dl className="docs-skills__metadata">
+                  {metadataEntries.map(([key, value]) => (
+                    <div key={key}>
+                      <dt>{key.replace(/[-_]+/g, ' ')}</dt>
+                      <dd>{metadataValue(value)}</dd>
+                    </div>
+                  ))}
+                </dl>
+              ) : null}
+              {selectedSkill.metadataIssue ? (
+                <p className="docs-skills__metadata-issue">Frontmatter could not be parsed: {selectedSkill.metadataIssue}</p>
+              ) : null}
+              <details className="docs-skills__source" open>
+                <summary>Full skill instructions</summary>
+                <pre><code>{selectedSkill.body}</code></pre>
+              </details>
+            </article>
+          ) : null}
+        </div>
+      ) : (
+        <p className="docs-skills__empty">
+          No SKILL.md files were found in this repository. Add skills under a .agents/skills or
+          .codex/skills folder, then rebuild the Docs site.
+        </p>
+      )}
+    </section>
+  );
+}
+
+export default SkillsExplorer;

package/site/src/lib/catalog.ts

@@ -1,6 +1,7 @@
 /// <reference types="vite/client" />
 
 import type { DocsNavNode } from '../../../src/components/navigation.js';
+import { getHue } from '@terra-symposium/styling';
 
 type SidebarFrontmatter = {
   label?: string;
@@ -110,6 +111,7 @@ for (const page of sitePages.filter((item) => !item.hidden && item.slug !== '404
     const overview = currentNodes.get('overview') ?? {
       id: 'overview',
       title: 'Overview',
+      hue: getHue('Overview'),
       children: new Map(),
     };
     if (!currentNodes.has('overview')) currentNodes.set('overview', overview);
@@ -120,7 +122,12 @@ for (const page of sitePages.filter((item) => !item.hidden && item.slug !== '404
     prefix = prefix ? `${prefix}/${segment}` : segment;
     let node = currentNodes.get(segment);
     if (!node) {
-      node = { id: prefix, title: label(segment), children: new Map() };
+      node = {
+        id: prefix,
+        title: label(segment),
+        ...(prefix === segment ? { hue: getHue(label(segment)) } : {}),
+        children: new Map(),
+      };
       currentNodes.set(segment, node);
     }
     current = node;

package/site/src/styles/skills-explorer.css

@@ -0,0 +1,268 @@
+.docs-skills {
+  margin-block: 2rem;
+}
+
+.docs-skills__header {
+  display: flex;
+  align-items: flex-end;
+  justify-content: space-between;
+  gap: 1.5rem;
+  margin-bottom: 1rem;
+}
+
+.docs-skills__header h2,
+.docs-skills__detail h3 {
+  margin: 0;
+}
+
+.docs-skills__header p:not(.docs-skills__eyebrow) {
+  margin: 0.4rem 0 0;
+  color: color-mix(in srgb, currentColor 72%, transparent);
+}
+
+.docs-skills__eyebrow {
+  margin: 0 0 0.35rem;
+  color: color-mix(in srgb, currentColor 64%, transparent);
+  font-size: 0.75rem;
+  font-weight: 700;
+  letter-spacing: 0.07em;
+  text-transform: uppercase;
+}
+
+.docs-skills__summary {
+  display: grid;
+  justify-items: end;
+  color: color-mix(in srgb, currentColor 70%, transparent);
+  font-size: 0.85rem;
+}
+
+.docs-skills__summary strong {
+  color: var(--docs-accent, currentColor);
+  font-size: 1.6rem;
+  line-height: 1;
+}
+
+.docs-skills__layout {
+  display: grid;
+  grid-template-columns: minmax(16rem, 0.8fr) minmax(0, 1.6fr);
+  align-items: start;
+  gap: 1rem;
+}
+
+.docs-skills__index,
+.docs-skills__detail {
+  min-width: 0;
+  overflow: hidden;
+  border: 1px solid color-mix(in srgb, currentColor 18%, transparent);
+  border-radius: 0.75rem;
+  background: color-mix(in srgb, currentColor 3%, transparent);
+}
+
+.docs-skills__index {
+  max-height: 78vh;
+  overflow: auto;
+  padding: 0.75rem;
+}
+
+.docs-skills__filter {
+  display: grid;
+  gap: 0.35rem;
+  font-size: 0.8rem;
+  font-weight: 600;
+}
+
+.docs-skills__filter input {
+  box-sizing: border-box;
+  width: 100%;
+  min-height: 2.5rem;
+  border: 1px solid color-mix(in srgb, currentColor 24%, transparent);
+  border-radius: 0.45rem;
+  background: var(--background, transparent);
+  color: inherit;
+  font: inherit;
+  font-weight: 400;
+  padding: 0.45rem 0.6rem;
+}
+
+.docs-skills__filter input:focus-visible,
+.docs-skills__item:focus-visible {
+  outline: 2px solid var(--docs-accent, currentColor);
+  outline-offset: 2px;
+}
+
+.docs-skills__count {
+  margin: 0.65rem 0 1rem;
+  color: color-mix(in srgb, currentColor 65%, transparent);
+  font-size: 0.8rem;
+}
+
+.docs-skills__group + .docs-skills__group {
+  margin-top: 1rem;
+}
+
+.docs-skills__group h3 {
+  margin: 0 0 0.4rem;
+  color: color-mix(in srgb, currentColor 68%, transparent);
+  font-size: 0.75rem;
+  font-weight: 700;
+  overflow-wrap: anywhere;
+  text-transform: uppercase;
+}
+
+.docs-skills__group ul {
+  display: grid;
+  gap: 0.35rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.docs-skills__item {
+  display: grid;
+  width: 100%;
+  min-width: 0;
+  gap: 0.2rem;
+  border: 0;
+  border-radius: 0.5rem;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+  font: inherit;
+  padding: 0.55rem;
+  text-align: left;
+}
+
+.docs-skills__item:hover,
+.docs-skills__item[aria-current='true'] {
+  background: color-mix(in srgb, var(--docs-accent, currentColor) 12%, transparent);
+}
+
+.docs-skills__item[aria-current='true'] .docs-skills__item-title {
+  color: var(--docs-accent, currentColor);
+  font-weight: 700;
+}
+
+.docs-skills__item-title {
+  font-weight: 600;
+}
+
+.docs-skills__item-description,
+.docs-skills__item-path {
+  color: color-mix(in srgb, currentColor 68%, transparent);
+  font-size: 0.78rem;
+  line-height: 1.4;
+}
+
+.docs-skills__item-path,
+.docs-skills__source-path {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  overflow-wrap: anywhere;
+}
+
+.docs-skills__detail > header {
+  padding: 1.25rem 1.25rem 0.75rem;
+}
+
+.docs-skills__description {
+  margin: 0.6rem 0;
+  color: color-mix(in srgb, currentColor 74%, transparent);
+}
+
+.docs-skills__source-path {
+  margin: 0;
+  color: color-mix(in srgb, currentColor 60%, transparent);
+  font-size: 0.75rem;
+}
+
+.docs-skills__metadata {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, 11rem), 1fr));
+  gap: 0.6rem;
+  margin: 0;
+  padding: 0.75rem 1.25rem 1.25rem;
+}
+
+.docs-skills__metadata > div {
+  min-width: 0;
+  border: 1px solid color-mix(in srgb, currentColor 15%, transparent);
+  border-radius: 0.5rem;
+  padding: 0.6rem 0.7rem;
+}
+
+.docs-skills__metadata dt {
+  color: color-mix(in srgb, currentColor 62%, transparent);
+  font-size: 0.72rem;
+  font-weight: 700;
+  text-transform: capitalize;
+}
+
+.docs-skills__metadata dd {
+  margin: 0.2rem 0 0;
+  font-size: 0.82rem;
+  overflow-wrap: anywhere;
+}
+
+.docs-skills__metadata-issue {
+  margin: 0 1.25rem 1rem;
+  color: #a12b2b;
+  font-size: 0.85rem;
+}
+
+.docs-skills__source {
+  border-top: 1px solid color-mix(in srgb, currentColor 16%, transparent);
+}
+
+.docs-skills__source summary {
+  cursor: pointer;
+  font-weight: 600;
+  padding: 0.8rem 1.25rem;
+}
+
+.docs-skills__source summary:focus-visible {
+  outline: 2px solid var(--docs-accent, currentColor);
+  outline-offset: -2px;
+}
+
+.docs-skills__source pre {
+  max-height: 60vh;
+  overflow: auto;
+  margin: 0;
+  border-top: 1px solid color-mix(in srgb, currentColor 12%, transparent);
+  background: color-mix(in srgb, currentColor 4%, transparent);
+  padding: 1rem 1.25rem;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 0.8rem;
+  line-height: 1.6;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+.docs-skills__empty {
+  border: 1px solid color-mix(in srgb, currentColor 18%, transparent);
+  border-radius: 0.75rem;
+  padding: 1rem;
+}
+
+@media (max-width: 48rem) {
+  .docs-skills__header {
+    align-items: flex-start;
+  }
+
+  .docs-skills__layout {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .docs-skills__index {
+    max-height: 45vh;
+  }
+}
+
+@media (max-width: 30rem) {
+  .docs-skills__header {
+    flex-direction: column;
+  }
+
+  .docs-skills__summary {
+    justify-items: start;
+  }
+}