Deploy Seqcolyte Studio

studio/deploy/hf/demo-seed/10x-pbmc-3-adapter-dimer-qc-demo-d13261/project.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "studio.project.v1",
   "id": "10x-pbmc-3-adapter-dimer-qc-demo-d13261",
-  "name": "10x Chromium 3\u2032 \u2014 adapter dimers",
+  "name": "10x Chromium 3′ — adapter dimers",
   "assay": "10x Chromium Single Cell 3' Gene Expression",
   "specId": "10x_3p_v3",
   "createdAt": "2026-07-09T00:09:57.059Z",
@@ -24,5 +24,6 @@
   "phase": "complete",
   "demo": true,
   "specConfirmed": true,
-  "demoBlurb": "A 10x short-read library with adapter dimers \u2014 QC flags the TSO-at-R2 and poly-G signatures and explains the fix."
+  "demoBlurb": "A 10x short-read library with adapter dimers — QC flags the TSO-at-R2 and poly-G signatures and explains the fix.",
+  "specMarkdownPath": "spec/spec.md"
 }

studio/deploy/hf/demo-seed/10x-pbmc-3-adapter-dimer-qc-demo-d13261/spec/spec.md

@@ -0,0 +1,71 @@
+# 10x 3' scRNA-seq (v3)
+
+**Assay:** 10x Chromium Single Cell 3' Gene Expression
+**Platform:** illumina · **Chemistry:** v3/v3.1
+
+Droplet-based single-cell 3' gene-expression profiling on Illumina. Cells are partitioned into gel-bead emulsions (GEMs); mRNA is barcoded during reverse transcription with a per-cell 16 nt barcode + 12 nt UMI, and the amplified cDNA is fragmented and built into a P5/P7-indexed short-read library. Profiles the transcriptomes of thousands of single cells per run.
+
+## Read structure
+
+- **R1** (bottom strand, 28 cycles): `cell_barcode:16` + `umi:12`
+- **I1** (bottom strand, 8 cycles): `sample_index_i7:8`
+- **R2** (top strand, 90 cycles): `cdna_insert`
+
+**R1 segments**
+
+| segment | type | length |
+| --- | --- | --- |
+| cell_barcode | barcode | 16 |
+| umi | umi | 12 |
+
+**I1 segments**
+
+| segment | type | length |
+| --- | --- | --- |
+| sample_index_i7 | index | 8 |
+
+**R2 segments**
+
+| segment | type | length |
+| --- | --- | --- |
+| cdna_insert | insert |  |
+
+## Oligos & adapters
+
+| id | role | sequence |
+| --- | --- | --- |
+| oligo_beads_oligo_dt | oligo | `CTACACGACGCTCTTCCGATCT[CELL_BARCODE:16][UMI:12]TTTTTTTTTTTTT…` |
+| oligo_template_switching_oligo_tso | oligo | `AAGCAGTGGTATCAACGCAGAGTACATGGG` |
+| oligo_cdna_forward_primer | primer | `CTACACGACGCTCTTCCGATCT` |
+| oligo_cdna_reverse_primer | primer | `AAGCAGTGGTATCAACGCAGAG` |
+| oligo_illumina_truseq_read_1_primer | primer | `ACACTCTTTCCCTACACGACGCTCTTCCGATCT` |
+| oligo_illumina_truseq_read_2_primer | primer | `GTGACTGGAGTTCAGACGTGTGCTCTTCCGATCT` |
+| oligo_truseq_adapter | adapter |  |
+| oligo_library_pcr_primer_1 | primer | `AATGATACGGCGACCACCGAGATCTACACTCTTTCCCTACACGACGCTC` |
+| oligo_library_pcr_primer_2 | primer | `CAAGCAGAAGACGGCATACGAGAT[SAMPLE_INDEX:8]GTGACTGGAGTTCAGACGTG…` |
+| oligo_sample_index_sequencing_primer | primer | `GATCGGAAGAGCACACGTCTGAACTCCAGTCAC` |
+| oligo_illumina_p5_adapter | adapter | `AATGATACGGCGACCACCGAGATCTACAC` |
+| oligo_illumina_p7_adapter | adapter | `CAAGCAGAAGACGGCATACGAGAT` |
+| oligo_r2_readthrough_adapter | read_through_adapter | `AGATCGGAAGAGCACACGTCTGAACTCCAGTCAC` |
+| oligo_r1_readinto_adapter | read_through_adapter | `AGATCGGAAGAGCGTCGTGTAGGGAAAGAGTGT` |
+| oligo_p5_rc | adapter_rc | `GTGTAGATCTCGGTGGTCGCCGTATCATT` |
+
+## Library preparation
+
+1. **mRNA capture using Beads-oligo-dT in the droplets, and reverse transcription using MMLV** — Poly(dT) beads capture mRNA in droplets; MMLV reverse-transcribes it into barcoded cDNA.
+2. **The terminal tranferase acitivity of MMLV adds extra Cs** — MMLV's terminal-transferase activity adds a few untemplated C's to the cDNA 3' end.
+3. **Adding TSO for second strand synthesis** — The TSO base-pairs with the C overhang to prime second-strand synthesis.
+4. **Adding cDNA Forward and Reverse primers to amplify full length cDNA** — cDNA Forward/Reverse primers PCR-amplify the full-length cDNA.
+5. **Use Fragmentase to fragment cDNA and perform A-tailing** — Fragmentase shears the cDNA and A-tails the fragment ends.
+6. **Add double stranded Illumina Truseq adapter (with a T overhang) for ligation** — A T-overhang TruSeq adapter is ligated onto the A-tailed fragments.
+7. **Add Library PCR Primers 1 & 2 to amplify library** — Library PCR primers 1 & 2 add P5/P7 and the i7 sample index.
+8. **Final library structure** — The final P5/P7-indexed Illumina paired-end library.
+
+## Final library (5'→3')
+
+```
+Illumina P5 | TruSeq Read 1 | cell barcode | UMI | poly(dT)VN | cDNA | TruSeq Read 2 | sample index (i7) | Illumina P7
+```
+
+---
+*Generated by Seqcolyte from the extracted library spec. Review it in the workspace, then click **Confirm spec** to run QC on your reads.*

studio/deploy/hf/demo-seed/10x-pbmc-3-healthy-library-demo-9ec7eb/project.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "studio.project.v1",
   "id": "10x-pbmc-3-healthy-library-demo-9ec7eb",
-  "name": "10x Chromium 3\u2032 \u2014 clean library",
+  "name": "10x Chromium 3′ — clean library",
   "assay": "10x Chromium Single Cell 3' Gene Expression",
   "specId": "10x_3p_v3",
   "createdAt": "2026-07-10T03:16:53.342Z",
@@ -24,5 +24,6 @@
     "20260710T031653Z-82a2fa"
   ],
   "demo": true,
-  "demoBlurb": "A clean 10x PBMC v3 short-read library \u2014 every QC check lands in range. The baseline for comparison."
+  "demoBlurb": "A clean 10x PBMC v3 short-read library — every QC check lands in range. The baseline for comparison.",
+  "specMarkdownPath": "spec/spec.md"
 }

studio/deploy/hf/demo-seed/10x-pbmc-3-healthy-library-demo-9ec7eb/spec/spec.md

@@ -0,0 +1,71 @@
+# 10x 3' scRNA-seq (v3)
+
+**Assay:** 10x Chromium Single Cell 3' Gene Expression
+**Platform:** illumina · **Chemistry:** v3/v3.1
+
+Droplet-based single-cell 3' gene-expression profiling on Illumina. Cells are partitioned into gel-bead emulsions (GEMs); mRNA is barcoded during reverse transcription with a per-cell 16 nt barcode + 12 nt UMI, and the amplified cDNA is fragmented and built into a P5/P7-indexed short-read library. Profiles the transcriptomes of thousands of single cells per run.
+
+## Read structure
+
+- **R1** (bottom strand, 28 cycles): `cell_barcode:16` + `umi:12`
+- **I1** (bottom strand, 8 cycles): `sample_index_i7:8`
+- **R2** (top strand, 90 cycles): `cdna_insert`
+
+**R1 segments**
+
+| segment | type | length |
+| --- | --- | --- |
+| cell_barcode | barcode | 16 |
+| umi | umi | 12 |
+
+**I1 segments**
+
+| segment | type | length |
+| --- | --- | --- |
+| sample_index_i7 | index | 8 |
+
+**R2 segments**
+
+| segment | type | length |
+| --- | --- | --- |
+| cdna_insert | insert |  |
+
+## Oligos & adapters
+
+| id | role | sequence |
+| --- | --- | --- |
+| oligo_beads_oligo_dt | oligo | `CTACACGACGCTCTTCCGATCT[CELL_BARCODE:16][UMI:12]TTTTTTTTTTTTT…` |
+| oligo_template_switching_oligo_tso | oligo | `AAGCAGTGGTATCAACGCAGAGTACATGGG` |
+| oligo_cdna_forward_primer | primer | `CTACACGACGCTCTTCCGATCT` |
+| oligo_cdna_reverse_primer | primer | `AAGCAGTGGTATCAACGCAGAG` |
+| oligo_illumina_truseq_read_1_primer | primer | `ACACTCTTTCCCTACACGACGCTCTTCCGATCT` |
+| oligo_illumina_truseq_read_2_primer | primer | `GTGACTGGAGTTCAGACGTGTGCTCTTCCGATCT` |
+| oligo_truseq_adapter | adapter |  |
+| oligo_library_pcr_primer_1 | primer | `AATGATACGGCGACCACCGAGATCTACACTCTTTCCCTACACGACGCTC` |
+| oligo_library_pcr_primer_2 | primer | `CAAGCAGAAGACGGCATACGAGAT[SAMPLE_INDEX:8]GTGACTGGAGTTCAGACGTG…` |
+| oligo_sample_index_sequencing_primer | primer | `GATCGGAAGAGCACACGTCTGAACTCCAGTCAC` |
+| oligo_illumina_p5_adapter | adapter | `AATGATACGGCGACCACCGAGATCTACAC` |
+| oligo_illumina_p7_adapter | adapter | `CAAGCAGAAGACGGCATACGAGAT` |
+| oligo_r2_readthrough_adapter | read_through_adapter | `AGATCGGAAGAGCACACGTCTGAACTCCAGTCAC` |
+| oligo_r1_readinto_adapter | read_through_adapter | `AGATCGGAAGAGCGTCGTGTAGGGAAAGAGTGT` |
+| oligo_p5_rc | adapter_rc | `GTGTAGATCTCGGTGGTCGCCGTATCATT` |
+
+## Library preparation
+
+1. **mRNA capture using Beads-oligo-dT in the droplets, and reverse transcription using MMLV** — Poly(dT) beads capture mRNA in droplets; MMLV reverse-transcribes it into barcoded cDNA.
+2. **The terminal tranferase acitivity of MMLV adds extra Cs** — MMLV's terminal-transferase activity adds a few untemplated C's to the cDNA 3' end.
+3. **Adding TSO for second strand synthesis** — The TSO base-pairs with the C overhang to prime second-strand synthesis.
+4. **Adding cDNA Forward and Reverse primers to amplify full length cDNA** — cDNA Forward/Reverse primers PCR-amplify the full-length cDNA.
+5. **Use Fragmentase to fragment cDNA and perform A-tailing** — Fragmentase shears the cDNA and A-tails the fragment ends.
+6. **Add double stranded Illumina Truseq adapter (with a T overhang) for ligation** — A T-overhang TruSeq adapter is ligated onto the A-tailed fragments.
+7. **Add Library PCR Primers 1 & 2 to amplify library** — Library PCR primers 1 & 2 add P5/P7 and the i7 sample index.
+8. **Final library structure** — The final P5/P7-indexed Illumina paired-end library.
+
+## Final library (5'→3')
+
+```
+Illumina P5 | TruSeq Read 1 | cell barcode | UMI | poly(dT)VN | cDNA | TruSeq Read 2 | sample index (i7) | Illumina P7
+```
+
+---
+*Generated by Seqcolyte from the extracted library spec. Review it in the workspace, then click **Confirm spec** to run QC on your reads.*

studio/deploy/hf/demo-seed/sc-nanopore-3-tso-concatemer-demo/project.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "studio.project.v1",
   "id": "sc-nanopore-3-tso-concatemer-demo",
-  "name": "sc-Nanopore 3\u2032 \u2014 TSO concatemers",
+  "name": "sc-Nanopore 3′ — TSO concatemers",
   "assay": "10x Chromium Single Cell 3' Gene Expression (Nanopore long-read)",
   "specId": "nanopore_10x_3p_direct_ligation",
   "createdAt": "2026-07-10T16:13:33.075625Z",
@@ -25,5 +25,6 @@
   "runIds": [
     "20260710T161333Z-28dc0a"
   ],
-  "demoBlurb": "A long-read sc-Nanopore library where 25.7% of reads are TSO concatemers \u2014 QC finds them and recommends read-splitting / biotin enrichment."
+  "demoBlurb": "A long-read sc-Nanopore library where 25.7% of reads are TSO concatemers — QC finds them and recommends read-splitting / biotin enrichment.",
+  "specMarkdownPath": "spec/spec.md"
 }

studio/deploy/hf/demo-seed/sc-nanopore-3-tso-concatemer-demo/spec/spec.md

@@ -0,0 +1,57 @@
+# sc-Nanopore 10x 3' cDNA (direct ligation)
+
+**Assay:** 10x Chromium Single Cell 3' Gene Expression amplified cDNA — baseline Oxford Nanopore direct-ligation simulation
+**Platform:** nanopore · **Chemistry:** v3.1/v4
+
+Full-length single-cell 3' cDNA sequenced on Oxford Nanopore. Amplified 10x cDNA (16 nt cell barcode + 12 nt UMI) is taken through ONT end-prep and ligation-adapter attachment and read end-to-end as one long read per molecule. This is a baseline direct-ligation simulation model; it omits the biotin-enrichment / streptavidin pull-down steps of the optimized ONT workflow.
+
+## Read structure
+
+- **L1** (normalized adapter1-first strand strand): `r1_handle:22` + `cell_barcode:16` + `umi:12` + `polyt` + `vn_anchor:2` + `cdna_insert` + `tso_rc:30`
+
+**L1 segments**
+
+| segment | type | length |
+| --- | --- | --- |
+| r1_handle | constant | 22 |
+| cell_barcode | barcode | 16 |
+| umi | umi | 12 |
+| polyt | homopolymer |  |
+| vn_anchor | anchor | 2 |
+| cdna_insert | insert |  |
+| tso_rc | constant | 30 |
+
+## Oligos & adapters
+
+| id | role | sequence |
+| --- | --- | --- |
+| oligo_beads_oligo_dt | Gel-bead-tethered RT primer: capture of poly(A) mRNA and addition of the 10x Barcode, UMI and partial TruSeq Read 1 handle | `CTACACGACGCTCTTCCGATCT[CELL_BARCODE:16][UMI:12]TTTTTTTTTTTTT…` |
+| oligo_template_switching_oligo_tso | Template switching at the cDNA 3' end; adds a constant handle used as the cDNA Reverse primer binding site | `AAGCAGTGGTATCAACGCAGAGTACATGGG` |
+| oligo_cdna_forward_primer | Bulk cDNA amplification (PCR), anneals to the partial TruSeq Read 1 handle | `CTACACGACGCTCTTCCGATCT` |
+| oligo_cdna_reverse_primer | Bulk cDNA amplification (PCR), anneals to the TSO-derived handle | `AAGCAGTGGTATCAACGCAGAG` |
+
+## Library preparation
+
+1. **mRNA capture on the gel-bead poly(dT) primer (GEM formation)** — mRNA is captured on the gel-bead poly(dT) primer as GEMs form.
+2. **Reverse transcription (GEM-RT, 53 C 45 min)** — GEM-RT makes barcoded first-strand cDNA.
+3. **Template Switch Oligo annealing** — The TSO anneals to the cDNA 3' C-overhang.
+4. **Template switching & transcript extension** — Template switching extends the transcript with the TSO handle into full-length cDNA.
+5. **cDNA amplification (bulk PCR with cDNA Primers, 11-13 cycles)** — Bulk PCR amplifies the full-length cDNA to build mass.
+6. **End repair & dA-tailing (ONT end-prep, NEBNext Ultra II)** — End repair + 3' dA-tailing prepares the amplicon for ligation (no fragmentation).
+7. **ONT ligation-adapter attachment (SQK-LSK114)** — ONT sequencing adapters (SQK-LSK114) are ligated directly to the full-length cDNA.
+8. **Nanopore sequencing — single-strand read, either orientation** — Each molecule is read end-to-end on the flow cell, in either orientation.
+
+## Final library (5'→3')
+
+```
+CTACACGACGCTCTTCCGATCT = R1 handle (partial TruSeq Read 1; 10x bead oligo)
+[CELL_BARCODE:16] = 16 bp 10x cell barcode
+[UMI:12] = 12 bp UMI
+TTTTTTTTTTTTTTTTTTTTTTTTTTTTTT = poly(dT) 30 nt
+VN = poly(dT)VN anchor (V=A/C/G, N=any)
+[CDNA] = full-length cDNA insert
+CCCATGTACTCTGCGTTGATACCACTGCTT = reverse complement of the TSO (DERIVED = reverse_complement(TSO)); 3' end
+```
+
+---
+*Generated by Seqcolyte from the extracted library spec. Review it in the workspace, then click **Confirm spec** to run QC on your reads.*

studio/src/app/api/projects/[id]/generate-spec/route.ts

@@ -0,0 +1,55 @@
+import { promises as fs } from "node:fs";
+import { NextResponse } from "next/server";
+import { getProject, updateProject } from "@/lib/store";
+import { inProject } from "@/lib/paths";
+import { readConversation } from "@/lib/chat";
+import { startExtract } from "@/lib/extractRunner";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+/**
+ * Build a spec from the user's free-text library description (typed in chat)
+ * instead of an uploaded protocol file. Saves the description as the project's
+ * lab notes and runs the same extractor `startExtract` uses, so the result flows
+ * into the normal review → Confirm-spec → run-QC path. The chat assistant is
+ * read-only and cannot do this itself — this is the workspace "Generate spec"
+ * button's endpoint.
+ */
+export async function POST(_req: Request, ctx: { params: Promise<{ id: string }> }) {
+  const { id } = await ctx.params;
+  let project;
+  try {
+    project = await getProject(id);
+  } catch {
+    return NextResponse.json({ error: "project not found" }, { status: 404 });
+  }
+
+  // The description is everything the user typed in chat (minus upload notices).
+  const conv = await readConversation(id);
+  const description = conv
+    .filter((e) => e.role === "user" && !e.text.startsWith("📎"))
+    .map((e) => e.text.trim())
+    .filter(Boolean)
+    .join("\n\n")
+    .trim();
+
+  if (description.length < 20) {
+    return NextResponse.json(
+      {
+        error:
+          "Describe your library structure in the chat first — read layout (R1/R2), UMI/barcode positions and lengths, and any adapters — then click Generate spec.",
+      },
+      { status: 400 },
+    );
+  }
+
+  // Persist as the project's lab notes (shown under Files) and extract from it.
+  const rel = project.inputs.notesPath || "inputs/notes.md";
+  await fs.mkdir(inProject(id, "inputs"), { recursive: true });
+  await fs.writeFile(inProject(id, rel), `${description}\n`, "utf8");
+  await updateProject(id, { inputs: { ...project.inputs, notesPath: rel } });
+
+  await startExtract(id, rel);
+  return NextResponse.json({ ok: true });
+}

studio/src/components/chat/chat.tsx

@@ -167,6 +167,8 @@ export function Chat({
   const [input, setInput] = useState("");
   const [uploading, setUploading] = useState(false);
   const [upload, setUpload] = useState<{ name: string; loaded: number; total: number } | null>(null);
+  const [dragActive, setDragActive] = useState(false);
+  const dragDepth = useRef(0);
   const [extract, setExtract] = useState<{ status: string; log: string; doc: string } | null>(null);
   const scrollRef = useRef<HTMLDivElement>(null);
   const fileRef = useRef<HTMLInputElement>(null);
@@ -242,10 +244,7 @@ export function Chat({
     };
   }
 
-  async function onPickFile(e: React.ChangeEvent<HTMLInputElement>) {
-    const file = e.target.files?.[0];
-    e.target.value = "";
-    if (!file) return;
+  async function uploadFile(file: File) {
     setUploading(true);
     setUpload({ name: file.name, loaded: 0, total: file.size });
     try {
@@ -268,8 +267,65 @@ export function Chat({
     }
   }
 
+  /** Upload one or more files sequentially (keeps R1/R2 slotting deterministic). */
+  async function uploadFiles(files: File[]) {
+    for (const f of files) await uploadFile(f);
+  }
+
+  async function onPickFile(e: React.ChangeEvent<HTMLInputElement>) {
+    const files = Array.from(e.target.files ?? []);
+    e.target.value = "";
+    if (files.length) await uploadFiles(files);
+  }
+
+  // --- drag-and-drop upload onto the whole chat surface ---
+  function hasFiles(e: React.DragEvent): boolean {
+    return Array.from(e.dataTransfer?.types ?? []).includes("Files");
+  }
+  function onDragEnter(e: React.DragEvent) {
+    if (!hasFiles(e)) return;
+    e.preventDefault();
+    dragDepth.current += 1;
+    setDragActive(true);
+  }
+  function onDragOver(e: React.DragEvent) {
+    if (hasFiles(e)) e.preventDefault(); // required for the drop event to fire
+  }
+  function onDragLeave(e: React.DragEvent) {
+    if (!hasFiles(e)) return;
+    dragDepth.current -= 1;
+    if (dragDepth.current <= 0) {
+      dragDepth.current = 0;
+      setDragActive(false);
+    }
+  }
+  async function onDrop(e: React.DragEvent) {
+    if (!hasFiles(e)) return;
+    e.preventDefault();
+    dragDepth.current = 0;
+    setDragActive(false);
+    if (uploading) return;
+    const files = Array.from(e.dataTransfer.files ?? []);
+    if (files.length) await uploadFiles(files);
+  }
+
   return (
-    <div className="flex h-full min-h-0 flex-col overflow-hidden">
+    <div
+      className="relative flex h-full min-h-0 flex-col overflow-hidden"
+      onDragEnter={onDragEnter}
+      onDragOver={onDragOver}
+      onDragLeave={onDragLeave}
+      onDrop={onDrop}
+    >
+      {dragActive && (
+        <div className="border-primary/50 bg-background/80 pointer-events-none absolute inset-2 z-20 flex flex-col items-center justify-center gap-2 rounded-lg border-2 border-dashed backdrop-blur-sm">
+          <Paperclip className="text-primary size-6" />
+          <div className="text-sm font-medium">Drop to upload</div>
+          <div className="text-muted-foreground text-xs">
+            protocol (PDF / txt / md), FASTQ reads, or design tables
+          </div>
+        </div>
+      )}
       <header className="border-border/60 flex shrink-0 items-center gap-2 border-b px-3 py-2.5">
         <button
           onClick={onToggleRail}
@@ -349,6 +405,7 @@ export function Chat({
           <input
             ref={fileRef}
             type="file"
+            multiple
             accept={UPLOAD_ACCEPT}
             className="hidden"
             onChange={onPickFile}

studio/src/components/files/files-panel.tsx

@@ -112,6 +112,16 @@ export function FilesPanel({
       downloadHref: `${fileHref(project.activeSpecPath)}?download`,
     });
   }
+  if (project.specMarkdownPath) {
+    const rel = project.specMarkdownPath;
+    rows.push({
+      icon: FileText,
+      label: "Spec (markdown)",
+      sub: "readable library summary",
+      open: { kind: "markdown", path: rel, title: "Spec" },
+      downloadHref: `${fileHref(rel)}?download`,
+    });
+  }
   for (const run of runs) {
     if (run.steps.qc?.status === "succeeded" || run.overall != null) {
       rows.push({

studio/src/components/workspace.tsx

@@ -2,7 +2,7 @@
 
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useRouter } from "next/navigation";
-import { Check, Loader2 } from "lucide-react";
+import { Check, Loader2, Sparkles } from "lucide-react";
 import { toast } from "sonner";
 import type { ImperativePanelHandle } from "react-resizable-panels";
 import type { ProjectManifest, RunRecord, StepStatus } from "@/lib/types";
@@ -35,6 +35,7 @@ export function Workspace({
   const [openFile, setOpenFile] = useState<OpenFile | null>(null);
   const [traceRunId, setTraceRunId] = useState<string | null>(initialRuns[0]?.id ?? null);
   const [confirming, setConfirming] = useState(false);
+  const [generating, setGenerating] = useState(false);
 
   const railRef = useRef<ImperativePanelHandle>(null);
   const viewerRef = useRef<ImperativePanelHandle>(null);
@@ -98,6 +99,52 @@ export function Workspace({
     }
   }, [project.id, router]);
 
+  // Build a spec from the user's chat description (no uploaded protocol needed),
+  // then poll until extraction resolves and reveal the spec for review.
+  const onGenerateSpec = useCallback(async () => {
+    setGenerating(true);
+    try {
+      const res = await fetch(`/api/projects/${project.id}/generate-spec`, { method: "POST" });
+      const data = (await res.json().catch(() => ({}))) as { ok?: boolean; error?: string };
+      if (!res.ok) {
+        toast.error(data.error ?? "Could not generate a spec");
+        setGenerating(false);
+        return;
+      }
+      const deadline = Date.now() + 3 * 60 * 1000;
+      const tick = async () => {
+        try {
+          const p = (await (
+            await fetch(`/api/projects/${project.id}`, { cache: "no-store" })
+          ).json()) as ProjectManifest;
+          if (p.phase === "awaiting_spec_review") {
+            setGenerating(false);
+            router.refresh();
+            openSpec();
+            return;
+          }
+          if (p.phase === "awaiting_inputs") {
+            setGenerating(false);
+            toast.error("Spec generation failed — see the chat for details");
+            router.refresh();
+            return;
+          }
+        } catch {
+          /* transient — keep polling */
+        }
+        if (Date.now() < deadline) setTimeout(tick, 1500);
+        else {
+          setGenerating(false);
+          toast.error("Spec generation timed out");
+        }
+      };
+      setTimeout(tick, 1500);
+    } catch {
+      setGenerating(false);
+      toast.error("Could not generate a spec");
+    }
+  }, [project.id, router, openSpec]);
+
   const onRunDone = useCallback(
     async (status: StepStatus, live: boolean) => {
       await refreshRuns();
@@ -150,12 +197,31 @@ export function Workspace({
       </button>
     ) : null;
 
+  const needsSpec = (project.phase ?? "awaiting_inputs") === "awaiting_inputs" && !project.activeSpecPath;
+
   return (
-    <ResizablePanelGroup
-      direction="horizontal"
-      autoSaveId="project-workspace"
-      className={cn("min-h-0", className)}
-    >
+    <div className={cn("flex min-h-0 flex-col", className)}>
+      {needsSpec && (
+        <div className="border-border/60 bg-muted/30 flex shrink-0 items-center gap-3 border-b px-4 py-2">
+          <Sparkles className="text-muted-foreground size-3.5 shrink-0" />
+          <span className="text-muted-foreground text-xs">
+            Described your library in the chat? Turn it into a reviewable spec, then confirm to run QC.
+          </span>
+          <button
+            onClick={onGenerateSpec}
+            disabled={generating}
+            className="border-primary/40 bg-primary/10 text-primary hover:bg-primary/20 ml-auto inline-flex shrink-0 items-center gap-1 rounded-md border px-2.5 py-1 text-xs font-medium disabled:opacity-50"
+          >
+            {generating ? <Loader2 className="size-3 animate-spin" /> : <Sparkles className="size-3" />}
+            {generating ? "Generating spec…" : "Generate spec"}
+          </button>
+        </div>
+      )}
+      <ResizablePanelGroup
+        direction="horizontal"
+        autoSaveId="project-workspace"
+        className="min-h-0 flex-1"
+      >
       <ResizablePanel
         id="rail"
         order={1}
@@ -214,6 +280,7 @@ export function Workspace({
           onRunDone={onRunDone}
         />
       </ResizablePanel>
-    </ResizablePanelGroup>
+      </ResizablePanelGroup>
+    </div>
   );
 }

studio/src/lib/chat.ts

@@ -188,6 +188,7 @@ export function buildGatingPreamble(project: ProjectManifest): string {
       hasOligoInfo ? (hasSpec ? "extracted into the spec" : "present in inputs") : "MISSING"
     }`,
     `- Reads: ${hasReads ? reads : "not chosen (a labeled demo dataset is available)"}`,
+    "CAPABILITY: You are a READ-ONLY assistant. You CANNOT run QC, extract, or confirm/commit a spec yourself — each of those is a button the user clicks in the workspace. NEVER claim you have run QC, 'confirmed'/'locked' a spec, or produced results, and never invent numbers. When the user asks you to run or confirm, name the exact button to click.",
   ];
 
   switch (phase) {
@@ -196,8 +197,8 @@ export function buildGatingPreamble(project: ProjectManifest): string {
         missing.length
           ? `GATE: Inputs are incomplete. Ask the user specifically for the MISSING item(s): ${missing.join(
               "; ",
-            )}. They can attach files with the 📎 button or describe the assay in chat. Do NOT start any analysis yet.`
-          : "GATE: Inputs look complete — offer to extract the spec / proceed.",
+            )}. They can attach files with the 📎 button, OR describe the library structure in chat and then click the "Generate spec" button at the top of the workspace to turn that description into a reviewable spec — describing it in chat alone does NOT create a spec. Do NOT claim to have built or run anything.`
+          : 'GATE: Inputs look complete. Point the user to the "Generate spec" button (or the 📎 protocol upload) to build the spec — you cannot build it yourself.',
       );
       break;
     case "extracting":

studio/src/lib/extractRunner.ts

@@ -186,6 +186,92 @@ function summarizeSpec(spec: SpecDoc): string {
   return lines.join("\n");
 }
 
+/** Human-readable markdown of the extracted spec — saved beside spec.json and shown under Files. */
+function renderSpecMarkdown(spec: SpecDoc): string {
+  const L: string[] = [];
+  const push = (s = "") => L.push(s);
+  const cell = (s: unknown) => String(s ?? "").replace(/\|/g, "\\|").replace(/\s*\n\s*/g, " ").trim();
+
+  const title = spec.title || spec.assay || "Sequencing library spec";
+  push(`# ${title}`);
+  push();
+  if (spec.assay && spec.assay !== title) push(`**Assay:** ${spec.assay}`);
+  const meta: string[] = [];
+  if (spec.platform) meta.push(`**Platform:** ${spec.platform}`);
+  if (spec.chemistry_version) meta.push(`**Chemistry:** ${spec.chemistry_version}`);
+  if (spec.modality) meta.push(`**Modality:** ${spec.modality}`);
+  if (spec.method_type) meta.push(`**Method:** ${spec.method_type}`);
+  if (meta.length) push(meta.join(" · "));
+  push();
+  if (spec.description) {
+    push(spec.description);
+    push();
+  }
+
+  const reads = spec.read_structure?.reads ?? [];
+  if (reads.length) {
+    push("## Read structure");
+    push();
+    for (const r of reads) {
+      const segs = (r.segments ?? [])
+        .map((s) => `\`${s.name}${s.length ? `:${s.length}` : ""}\``)
+        .join(" + ");
+      const tail = [r.template ? `${r.template} strand` : "", r.cycles ? `${r.cycles} cycles` : ""]
+        .filter(Boolean)
+        .join(", ");
+      push(`- **${r.read}**${tail ? ` (${tail})` : ""}${segs ? `: ${segs}` : ""}`);
+    }
+    push();
+    for (const r of reads) {
+      if (!r.segments?.length) continue;
+      push(`**${r.read} segments**`);
+      push();
+      push("| segment | type | length |");
+      push("| --- | --- | --- |");
+      for (const s of r.segments) push(`| ${cell(s.name)} | ${cell(s.type)} | ${cell(s.length)} |`);
+      push();
+    }
+  }
+
+  if (spec.oligos?.length) {
+    push("## Oligos & adapters");
+    push();
+    push("| id | role | sequence |");
+    push("| --- | --- | --- |");
+    for (const o of spec.oligos) {
+      const seq = o.sequence
+        ? `\`${o.sequence.length > 60 ? o.sequence.slice(0, 60) + "…" : o.sequence}\``
+        : "";
+      push(`| ${cell(o.oligo_id)} | ${cell(o.role ?? o.kind)} | ${seq} |`);
+    }
+    push();
+  }
+
+  if (spec.library_generation?.length) {
+    push("## Library preparation");
+    push();
+    for (const st of spec.library_generation) {
+      push(`${st.step}. **${st.title}**${st.summary ? ` — ${st.summary}` : ""}`);
+    }
+    push();
+  }
+
+  if (spec.final_library?.annotation_lines?.length) {
+    push("## Final library (5'→3')");
+    push();
+    push("```");
+    for (const line of spec.final_library.annotation_lines) push(line);
+    push("```");
+    push();
+  }
+
+  push("---");
+  push(
+    "*Generated by Seqcolyte from the extracted library spec. Review it in the workspace, then click **Confirm spec** to run QC on your reads.*",
+  );
+  return L.join("\n");
+}
+
 export async function startExtract(projectId: string, docRel: string): Promise<void> {
   if (live.has(projectId)) return;
   live.add(projectId);
@@ -286,6 +372,14 @@ async function driveExtract(
     phase: "awaiting_spec_review",
     specConfirmed: false,
   };
+  // Save a readable markdown of the spec beside the JSON, surfaced under Files.
+  try {
+    const mdRel = "spec/spec.md";
+    await fs.writeFile(inProject(projectId, mdRel), renderSpecMarkdown(spec), "utf8");
+    patch.specMarkdownPath = mdRel;
+  } catch {
+    /* markdown is a convenience artifact — never fail extraction over it */
+  }
   if (spec.assay) patch.assay = spec.assay;
   // Adopt the identified id only when it's a known structure; a custom library
   // keeps the neutral "new" tag rather than inventing a fake catalog id.

studio/src/lib/types.ts

@@ -88,6 +88,8 @@ export interface ProjectManifest {
   updatedAt: string;
   /** relative-to-project path of the active spec (extract output or reference copy) */
   activeSpecPath: string | null;
+  /** relative-to-project path of the human-readable spec markdown (written beside the spec JSON) */
+  specMarkdownPath?: string | null;
   /** Current lifecycle phase (defaults to awaiting_inputs when absent). */
   phase?: ProjectPhase;
   /** The user reviewed and confirmed the extracted spec. */