Focus the CLI docs on users and rewrite the compute guide

components/compute-layers.tsx

@@ -0,0 +1,88 @@
+import Link from 'fumadocs-core/link';
+import { Laptop, Server } from 'lucide-react';
+import type { CSSProperties, ReactNode } from 'react';
+
+// How lc reaches compute, drawn like the stack diagram: the commands that
+// execute the analysis, the lc compute layer that allocates for them, and the
+// providers that ~/.lightcone/compute.yaml lists. Brand colours follow the
+// light and dark schemes.
+const providers = [
+  { name: 'Your machine', provider: 'local', href: '#on-your-machine', icon: Laptop },
+  { name: 'Slurm cluster', provider: 'slurm', href: '#slurm', icon: Server },
+];
+
+function tint(color: string): CSSProperties {
+  return {
+    background: `color-mix(in srgb, ${color} 14%, var(--color-fd-card))`,
+    borderColor: `color-mix(in srgb, ${color} 45%, var(--color-fd-border))`,
+  };
+}
+
+// One layer, with its note to the right on wide screens and below it on narrow ones.
+function Layer({ note, children }: { note: ReactNode; children: ReactNode }) {
+  return (
+    <div className="grid items-center gap-x-3 gap-y-1 sm:grid-cols-[minmax(0,1fr)_15rem]">
+      {children}
+      <p className="flex items-center gap-2 text-sm text-fd-muted-foreground">
+        <span
+          aria-hidden
+          className="hidden w-6 shrink-0 border-t-2 border-dotted border-fd-muted-foreground/40 sm:block"
+        />
+        <span>{note}</span>
+      </p>
+    </div>
+  );
+}
+
+const box =
+  'whitespace-nowrap rounded-lg border px-2 py-3 text-center text-sm text-fd-foreground transition-shadow hover:shadow-md sm:px-4 sm:text-base';
+
+export function ComputeLayers() {
+  return (
+    <figure aria-label="How lc reaches compute" className="not-prose my-6 flex flex-col gap-2">
+      <Layer note="Execute your analysis">
+        <div className="grid grid-cols-2 gap-2">
+          <Link href="/lightcone-cli/commands/run" className={box} style={tint('var(--lc-color-vert-de-gris)')}>
+            <code>lc run</code>
+          </Link>
+          <Link
+            href="/lightcone-cli/commands/materialize"
+            className={box}
+            style={tint('var(--lc-color-vert-de-gris)')}
+          >
+            <code>lc materialize</code>
+          </Link>
+        </div>
+      </Layer>
+      <Layer note="Allocate and stop compute">
+        <Link href="/lightcone-cli/commands/compute" className={box} style={tint('var(--lc-color-antique-gold)')}>
+          <code>lc compute</code>
+        </Link>
+      </Layer>
+      <Layer
+        note={
+          <>
+            Configured in <code>compute.yaml</code>
+          </>
+        }
+      >
+        <div className="rounded-lg border bg-fd-card p-3">
+          <p className="mb-2 text-center text-sm font-medium text-fd-foreground">Compute providers</p>
+          <div className="grid grid-cols-2 gap-2">
+            {providers.map(({ name, provider, href, icon: Icon }) => (
+              <Link
+                key={provider}
+                href={href}
+                className="flex flex-col items-center gap-1 rounded-md border bg-fd-background px-3 py-3 text-center transition-shadow hover:shadow-md"
+              >
+                <Icon aria-hidden className="size-6 text-fd-muted-foreground" />
+                <span className="text-sm font-medium text-fd-foreground">{name}</span>
+                <code className="text-xs text-fd-muted-foreground">provider: {provider}</code>
+              </Link>
+            ))}
+          </div>
+        </div>
+      </Layer>
+    </figure>
+  );
+}

components/mdx.tsx

@@ -3,6 +3,7 @@ import { Step, Steps } from 'fumadocs-ui/components/steps';
 import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
 import type { MDXComponents } from 'mdx/types';
 import { StackLayers } from '@/components/stack-layers';
+import { ComputeLayers } from '@/components/compute-layers';
 
 export function getMDXComponents(components?: MDXComponents) {
   return {
@@ -12,6 +13,7 @@ export function getMDXComponents(components?: MDXComponents) {
     Tab,
     Tabs,
     StackLayers,
+    ComputeLayers,
     ...components,
   } satisfies MDXComponents;
 }

content/docs/(stack)/meta.json

@@ -10,7 +10,7 @@
     "astra",
     "comparisons",
     "installation",
-    "---[Book]Guides---",
+    "---Guides---",
     "...guides"
   ]
 }

content/docs/(stack)/quickstart.mdx

@@ -171,7 +171,7 @@ lc status                             # see which results are out of date, and w
 ```
 
 The local cluster stops on its own after 30 minutes without work. Run these yourself, or ask your
-agent to. The [`lc` reference](/lightcone-cli/commands) covers every command.
+agent to. The [`lc` docs](/lightcone-cli) cover every command.
 
 ## Learn more
 
@@ -191,8 +191,8 @@ agent to. The [`lc` reference](/lightcone-cli/commands) covers every command.
   <Card title="Lightcone Lab" href="/lightcone-lab">
     Get more out of the workbench, including agent sessions inside JupyterLab.
   </Card>
-  <Card title="Running on a cluster" href="/lightcone-cli/cluster">
-    Run the analysis on local or Slurm compute.
+  <Card title="Configuring compute" href="/lightcone-cli/configuring-compute">
+    Run the analysis on local or Slurm compute, with or without GPUs.
   </Card>
   <Card title="MySTRA" href="/mystra">
     Write up the analysis in a report that cites its results.

content/docs/agent-skills/meta.json

@@ -8,7 +8,7 @@
     "index",
     "getting-started",
     "installation",
-    "---[Book]Guides---",
+    "---Guides---",
     "lightcone",
     "astra",
     "---Reference---",