Serve the docs from the root, with a project selector

app/docs/[[...slug]]/page.tsx → app/(docs)/[[...slug]]/page.tsx

@@ -13,7 +13,7 @@ import type { Metadata } from 'next';
 import { createRelativeLink } from 'fumadocs-ui/mdx';
 import { getPageImageUrl, getPageMarkdownUrl, gitConfig } from '@/lib/shared';
 
-export default async function Page(props: PageProps<'/docs/[[...slug]]'>) {
+export default async function Page(props: PageProps<'/[[...slug]]'>) {
   const params = await props.params;
   const page = source.getPage(params.slug);
   if (!page) notFound();
@@ -24,7 +24,7 @@ export default async function Page(props: PageProps<'/docs/[[...slug]]'>) {
   return (
     <DocsPage toc={page.data.toc} full={page.data.full}>
       <DocsTitle>{page.data.title}</DocsTitle>
-      <DocsDescription className="mb-0">{page.data.description}</DocsDescription>
+      <DocsDescription className="mb-0 text-(--lc-color-slate-blue)">{page.data.description}</DocsDescription>
       <div className="flex flex-row gap-2 items-center border-b pb-6">
         <MarkdownCopyButton markdownUrl={markdownUrl} />
         <ViewOptionsPopover
@@ -48,7 +48,7 @@ export async function generateStaticParams() {
   return source.generateParams();
 }
 
-export async function generateMetadata(props: PageProps<'/docs/[[...slug]]'>): Promise<Metadata> {
+export async function generateMetadata(props: PageProps<'/[[...slug]]'>): Promise<Metadata> {
   const params = await props.params;
   const page = source.getPage(params.slug);
   if (!page) notFound();

app/(docs)/layout.tsx

@@ -0,0 +1,18 @@
+import { source } from '@/lib/source';
+import { GlassLayout } from 'fumadocs-ui/layouts/glass';
+import { getLayoutTabs } from 'fumadocs-ui/layouts/shared';
+import { baseOptions } from '@/lib/layout.shared';
+
+export default function Layout({ children }: LayoutProps<'/'>) {
+  const tree = source.getPageTree();
+  // The project selector. The default transform stretches each icon to fill its
+  // box, which suits the Docs layout's tabs but not Glass's dropdown, so the
+  // icons are kept as the loader renders them (as fumadocs.dev does).
+  const tabs = getLayoutTabs(tree, { transform: (option) => option });
+
+  return (
+    <GlassLayout tree={tree} tabs={tabs} {...baseOptions()}>
+      {children}
+    </GlassLayout>
+  );
+}

app/lightcone.css

@@ -19,7 +19,7 @@
   --color-fd-background: var(--lc-color-surface);
   --color-fd-foreground: var(--lc-color-text);
   --color-fd-muted: var(--lc-color-surface-muted);
-  --color-fd-muted-foreground: var(--lc-color-text-subtle);
+  --color-fd-muted-foreground: var(--lc-color-text-muted);
   --color-fd-popover: var(--lc-color-canvas);
   --color-fd-popover-foreground: var(--lc-color-text);
   --color-fd-card: var(--lc-color-canvas);

content/docs/(stack)/index.mdx

@@ -0,0 +1,38 @@
+---
+title: Introduction
+description: From research question to reproducible result.
+---
+
+import { Bot, FlaskConical, PenLine, Terminal } from 'lucide-react';
+
+The Lightcone Research Stack is Lightcone Research's tooling for research analyses described
+with [ASTRA](https://astra-spec.org/latest/). You describe an analysis in an `astra.yaml`
+specification; the stack runs it, keeps every result tied to the choices that produced it, and
+carries it through to a written report.
+
+<Callout title="Being rebuilt">
+  This site is being reorganised around the whole stack. A quickstart and guides are on their way;
+  until then, each component's section links to its current documentation.
+</Callout>
+
+## Components
+
+Choose a component from the selector at the top of the sidebar, or start here:
+
+<Cards>
+  <Card icon={<Terminal />} title="Lightcone CLI" href="/lightcone-cli">
+    The `lc` command: runs an analysis and records the provenance of every output.
+  </Card>
+  <Card icon={<Bot />} title="Agent Skills" href="/agent-skills">
+    Plugins that teach coding agents to scope, build and run ASTRA analyses.
+  </Card>
+  <Card icon={<FlaskConical />} title="Lightcone Lab" href="/lightcone-lab">
+    A JupyterLab workbench for exploring an ASTRA project.
+  </Card>
+  <Card icon={<PenLine />} title="MySTRA" href="/mystra">
+    Write reports that reference an analysis instead of copying its results.
+  </Card>
+</Cards>
+
+The ASTRA specification and the `astra` command have their own documentation at
+[astra-spec.org](https://astra-spec.org/latest/).

content/docs/(stack)/meta.json

@@ -0,0 +1,7 @@
+{
+  "title": "Lightcone Stack",
+  "description": "Quickstart and guides for the whole stack",
+  "icon": "Layers",
+  "root": true,
+  "pages": ["index", "---Related---", "external:[ASTRA specification](https://astra-spec.org/latest/)"]
+}

content/docs/agent-skills/index.mdx

@@ -0,0 +1,17 @@
+---
+title: Overview
+description: Plugins that teach coding agents to work with the Lightcone stack.
+---
+
+Agent Skills are plugins, in the open Agent Skills format, that teach coding agents such as
+Claude Code and Codex to work with the stack.
+
+- The **astra** plugin covers writing `astra.yaml` specifications, and validates them as the agent
+  saves.
+- The **lightcone** plugin includes astra, and adds guidance for scoping, running, reporting on
+  and publishing a Lightcone project.
+
+<Callout title="Moving here">
+  This section is being migrated. Until then, see the current
+  [Agent Skills documentation](https://lightconeresearch.github.io/agent-skills/latest/).
+</Callout>

content/docs/agent-skills/meta.json

@@ -0,0 +1,7 @@
+{
+  "title": "Agent Skills",
+  "description": "Plugins that teach coding agents the stack",
+  "icon": "Bot",
+  "root": true,
+  "pages": ["index"]
+}

content/docs/lightcone-cli/index.mdx

@@ -0,0 +1,17 @@
+---
+title: Overview
+description: The lc command runs an ASTRA analysis and records the provenance of every output.
+---
+
+The Lightcone CLI, `lc`, is the execution layer of the stack. It turns an `astra.yaml`
+specification into outputs produced in a sandbox and committed with git and git-annex, with
+provenance recorded for each one. It runs every variant of an analysis (its universes) and reuses
+outputs that are already up to date.
+
+`lc` is built to be driven by people and coding agents alike: its commands never prompt, and most
+of them report in JSON with `--json`.
+
+<Callout title="Moving here">
+  This section is being migrated. Until then, see the current
+  [Lightcone CLI documentation](https://lightconeresearch.github.io/lightcone-cli/latest/).
+</Callout>

content/docs/lightcone-cli/meta.json

@@ -0,0 +1,7 @@
+{
+  "title": "Lightcone CLI",
+  "description": "The lc command: run analyses with provenance",
+  "icon": "Terminal",
+  "root": true,
+  "pages": ["index"]
+}

content/docs/lightcone-lab/index.mdx

@@ -0,0 +1,16 @@
+---
+title: Overview
+description: A JupyterLab workbench for exploring and working on ASTRA projects.
+---
+
+Lightcone Lab is a JupyterLab extension that turns JupyterLab into a workbench for ASTRA projects:
+a project home, an inventory of the analysis and its pipeline, provenance and version comparison,
+comments, project-aware agents, and a viewer for the project's MySTRA report.
+
+It runs as a browser-only workbench, or with its `full` extra for the features that need the
+Jupyter server, such as running the Lightcone CLI and agents.
+
+<Callout title="Moving here">
+  This section is being written. Until then, see the
+  [Lightcone Lab README](https://github.com/LightconeResearch/jupyterlab-lightcone).
+</Callout>

content/docs/lightcone-lab/meta.json

@@ -0,0 +1,7 @@
+{
+  "title": "Lightcone Lab",
+  "description": "A JupyterLab workbench for ASTRA projects",
+  "icon": "FlaskConical",
+  "root": true,
+  "pages": ["index"]
+}

content/docs/meta.json

@@ -0,0 +1,3 @@
+{
+  "pages": ["(stack)", "lightcone-cli", "agent-skills", "lightcone-lab", "mystra"]
+}

content/docs/mystra/index.mdx

@@ -0,0 +1,14 @@
+---
+title: Overview
+description: A MyST plugin for reports that reference an ASTRA analysis instead of copying it.
+---
+
+MySTRA is a plugin for [MyST](https://mystmd.org/) Markdown. A report written with it refers to
+the parts of an ASTRA analysis, such as its decisions, results and values, by path instead of
+copying them, so the report stays in step with the analysis. Projects created with `lc init` are
+already set up to use it.
+
+<Callout title="Moving here">
+  This section is being migrated. Until then, see the current
+  [MySTRA documentation](https://lightconeresearch.github.io/MySTRA/).
+</Callout>

content/docs/mystra/meta.json

@@ -0,0 +1,7 @@
+{
+  "title": "MySTRA",
+  "description": "Reference ASTRA analyses in MyST reports",
+  "icon": "PenLine",
+  "root": true,
+  "pages": ["index"]
+}

lib/shared.ts

@@ -1,7 +1,7 @@
 import { createGetUrl } from 'fumadocs-core/source';
 
 export const appName = 'Lightcone Research Stack';
-export const docsRoute = '/docs';
+export const docsRoute = '/';
 export const docsImageRoute = '/og/docs';
 export const docsContentRoute = '/llms.mdx/docs';
 

lib/source.ts

@@ -1,4 +1,5 @@
 import { llms, loader } from 'fumadocs-core/source';
+import { lucideIconsPlugin } from 'fumadocs-core/source/lucide-icons';
 import { docsContentRoute, docsImageRoute, docsRoute } from './shared';
 import { defineDocs } from 'fumadocs-mdx/macro';
 import { metaSchema, pageSchema } from 'fumadocs-core/source/schema';
@@ -20,7 +21,8 @@ const docs = defineDocs({
 export const source = loader({
   baseUrl: docsRoute,
   source: docs.toFumadocsSource(),
-  plugins: [],
+  // Resolves `icon` names in frontmatter and meta.json, such as each project's icon in the selector.
+  plugins: [lucideIconsPlugin()],
 });
 
 export const docsLlms = llms(source, {