Repository navigation
Expand file tree
/
Copy pathindex.qmd
More file actions
1875 lines (1467 loc) · 86.3 KB
/
Copy pathindex.qmd
File metadata and controls
1875 lines (1467 loc) · 86.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
---
title: "Quarto Workshop"
subtitle: "🤖 AI-assisted reproducible publishing with Quarto"
author: "Ravi Kalia, PhD"
# The author's profile, linked beside the name; the e-book page reads it from here (ebook/_source.py).
author-linkedin: "https://www.linkedin.com/in/ravi-kalia-phd/"
date: ""
title-note: "🌍 Spanish or another language? The
[Google Translate extension](https://chromewebstore.google.com/detail/google-translate/aapbdbdomjkkjkaonfhkkikfgjllcleb)
translates these slides; code stays as written."
book-note: "📖 Prefer reading? The workshop is also a [free e-book →](ebook/) · [en español](ebook/es/)"
title-qr:
url: "https://project-delphi.github.io/quarto-workshop/"
image: "assets/deck-qr.svg"
caption: "📱 Scan to open these slides"
# Shown as text beside the code for anyone who would rather type; it redirects to `url`.
short: "tinyurl.com/quarto-ai"
# The 📖 Get the Book slide's QR code and links; scripts/deck_qr.py draws the code from `url`,
# and ebook/index.qmd stops if `url` is not its own address.
ebook-qr:
url: "https://project-delphi.github.io/quarto-workshop/ebook/"
image: "assets/ebook-qr.svg"
epub: "https://github.com/project-delphi/quarto-workshop/releases/latest/download/prompt-check-publish.epub"
template-partials:
- assets/title-slide.html
description: "AI-assisted reproducible publishing with Quarto: a hands-on workshop where you direct a coding agent, check its work, and rebuild one source into docx, pdf, pptx, revealjs slides, epub, a website, a blog and a dashboard, using a London guide and Colombian water-safety data."
---
## 🤖 AI Usage Statement for These Slides {#ai-use-deck}
> These slides were written with **Claude Code** (Claude Opus 5.5, Sonnet 5.5, Opus 5 and Fable 5.1),
> which drafted slides, Quarto files and code and re-rendered the deck.
> The author directed the work, reviewed and ran the code, and takes full responsibility for the content.
. . .
🏷️ Tool + version · 🛠️ Tasks · ✅ Checks · 🙋 Accountability · [📜 what a statement needs](#ai-policy)
::: {.notes}
This is the statement for this repository, written the way the workshop asks participants to
write theirs (see 📜 Using AI in Research, in 📖 Read Before the Day). The tool and models are read from the
`Co-Authored-By` lines of the commit history, checked 2026-11-05: Claude Code with Claude
Opus 5.5 (most commits), Sonnet 5.5, Opus 5 and Fable 5.1. The author edits this slide if
the history is incomplete (for example, another agent, such as Codex, used without a
trailer), and updates the model list when new commits use other models. The data in the
worked examples are public sources named in `data/README.md`, not AI output, and the rules
in `AGENTS.md` require every number to be computed from the input data. The author confirms
the "reviewed and ran" claim before teaching.
:::
## 🗓️ Agenda {#agenda}
::: {style="font-size: 0.88em"}
🇬🇧 **Part 1:** a London guide · 💧 **Part 2:** Colombian water-quality research
| ⏱️ | Block | Min |
|---|---|--:|
| 0:00 | 👋 Welcome · 🎯 objective · 🏁 outcome | 10 |
| 0:10 | 🧭 What Is Quarto? | 5 |
| 0:15 | 🧰 Ready to Prompt · ✋ fix failed checks · boxes · 🗣️ prompting | 15 |
| 0:30 | 🇬🇧 Part 1 · London: Markdown → HTML, rules, environment | 35 |
| 1:05 | **☕ Break · 🛟 catch up** | 15 |
| 1:20 | 🇬🇧 Part 1 · `.qmd` · 🗂️ three audiences · 🌍 publish · 🔁 change an input | 65 |
| 2:25 | **🍽️ Meal Break · 🛟 catch up** | 30 |
| 2:55 | 💧 Part 2 · Colombian water quality: why · data · 🔍 explore · 🧹 prepare · 🧩 cluster | 85 |
| 4:20 | **☕ Break · 🛟 catch up** | 15 |
| 4:35 | 💧 Part 2 · 🏷️ Interpret · ⚠️ correlation ≠ causation · 📤 publish many | 75 |
| 5:50 | 🏁 Done · 🔗 show your sites · 👋 finish at **6:00** | 10 |
: {tbl-colwidths="[10,80,10]"}
:::
[🏠 before the workshop: [🛠️ Setup](#setup), 6 steps · then [📖 Read Before the Day](#read-before) · ⭐ = optional, self-paced]{.source}
::: {.notes}
Section dividers show the same start times, and Parts 1 and 2 each have an agenda slide with
every block's time. The day is 360 minutes: 300 of teaching in four sessions (65, 65, 85 and
85 minutes) and 60 of breaks. A 15-minute break follows Part 1's first block, the 30-minute
meal falls between the parts, and a second 15-minute break follows Part 2's Cluster block,
its hardest. Times count from the start of the day, so add your start time: from 9:30, the
meal is at 11:55 and the day ends at 15:30. Part 1 demonstrates
rather than requires the pptx, epub and revealjs exports and the square social ad (⭐), and
builds its three audience versions with one prompt that runs sub-agents in parallel. Each
part ends with a task that has no supplied prompt: change an input, rebuild and explain
which outputs update. In Part 2 the dashboard and ePub are ⭐, and the normal 📤 route copies
the finished k-means step. The meal also absorbs a slow publish: anyone whose London
site is not live yet finishes it then, with help. The two 🏠 sections are pre-work: 🛠️ Setup
(installing the tools, the setup check and the test run) and 📖 Read Before the Day (the
agent, models and costs, AI policy and Markdown in Y minutes), which frees the time for
Part 1's first block: participants meet the agent, the project rules, the preview and
the Python environment there, which is when recovery takes longest. The 🏠 exercises
(the six setup steps 20, 4, 5, 10, 4 and 5 min, and Markdown 5 min: 53 min in all) are timed
for home: collect each
participant's test-run confirmation before the day and contact anyone who has not sent
one. In the room, the 0:15 block first asks who has a failing check: a helper sits with each
of them to re-run it and the test run (about nine minutes) while the presenter carries on
with the boxes and prompting slides, so the room never waits for a re-run.
Exercise times never fill a block: the
rest is for showing results and fixing a failed command. ⭐ slides are optional and
self-paced, there for people ahead of the room. These are planning estimates; rehearse with
a stopwatch and change the agenda, the section clocks and README together.
:::
## 🎯 Objective · 🏁 Outcome {#objective}
::: {.goal}
[🎯 Objective]{.goal-label}
Publish **reproducible content** with **Quarto**, written by a coding agent you **direct and check**.
:::
. . .
::: {.goal .goal-outcome}
[🏁 Outcome]{.goal-label}
Plain-text Markdown becomes
::: {.chips}
[📄 docx]{} [📕 pdf]{} [📊 pptx]{} [🎞️ revealjs]{} [📖 epub ⭐]{} [🌐 website]{} [✍️ blog]{} [📈 dashboard]{}
:::
🤖 with the code written by your coding agent
🔁 change an input, rebuild, and explain what updated
:::
::: {.source}
🌍 [¿Prefieres leer en español? La extensión Google Translate traduce estas diapositivas; el código no cambia.]{lang="es"} ·
[Google Translate](https://chromewebstore.google.com/detail/google-translate/aapbdbdomjkkjkaonfhkkikfgjllcleb)
:::
::: {.notes}
Audience: people new to Quarto, many with only a rudimentary grasp of Linux, the terminal or
installing tools; the setup path teaches the little they need. Prerequisites: a GitHub account
and a coding agent account; the setup slides install the rest.
Completion: a published London dashboard URL, a published water-safety site, and for each
project an explanation of which outputs update when an input changes.
The slides are the course resource: participants can follow them alone. Most steps
are done by prompting the coding agent; the green boxes are the few things people
type themselves.
:::
## 🌍 Expected Outcomes {#expected-outcomes}
Create and publish **online content** like these examples:
::: {.cards .outcomes}
::: {}
[🇬🇧]{.big}
**[London guide](https://project-delphi.github.io/london-guide/)**
Travel guide · dashboard · flyer
:::
::: {}
[💧]{.big}
**[Colombian water safety](https://project-delphi.github.io/water-quality/)**
Analysis · report · blog
:::
::: {}
[✍️]{.big}
**[ML blog](https://project-delphi.github.io/ml-blog/)**
Posts · code · math
:::
:::
🧩 All three, and **[these slides](https://github.com/project-delphi/quarto-workshop)**
(📄 [index.qmd](https://github.com/project-delphi/quarto-workshop/blob/main/index.qmd)),
are built with Quarto.
🔗 Finish with **your own shareable websites**.
::: {.notes}
Say it out loud: this deck is itself a Quarto Reveal.js website, written in Markdown
and rendered from source, the same way participants will build theirs. The 📄 link opens
its source, `index.qmd`, on GitHub: an example of the `.qmd` files participants will write
(Parts 1 and 2 are included from `slides/_london.qmd` and `slides/_water.qmd`).
Open the three linked examples to show the workshop's expected outcomes: online content
that other people can visit and explore. Part 1 builds and publishes a London guide;
Part 2 builds and publishes a Colombian water-safety analysis site, including a blog
post. The ML blog ("Synthetic Musings", the deck author's own blog) is not built in
the workshop: it shows where the same blog format leads, a standing site of posts that
mix prose, code and math. Participants
finish with their own working public URLs, alongside the downloadable formats on the
previous slide. Use these examples as a preview of the destination; the steps follow
throughout the workshop.
:::
# 🧭 What Is Quarto? {#what-is-quarto}
[⏱️ 0:10]{.clock}
## Quarto = Markdown → Anything {#quarto-hub}
{fig-alt="Two inputs, a .md Markdown file and a .qmd file with code in Python, R, bash, SQL, MATLAB, Java, JavaScript or C, flow into Quarto, shown by its four-quadrant logo, which combines Pandoc with Jupyter and knitr. Quarto produces four groups of formats: documents (html, pdf, docx, odt and, highlighted, epub); presentations (revealjs, pptx, beamer); the web (website, blog, dashboard); and more (Markdown, Jupyter notebooks, JATS, wikis)." width="74%" fig-align="center"}
🆓 **Free and open source** · no licence to buy, for anyone · [MIT License](https://quarto.org/license.html)
[📚 [All Quarto output formats](https://quarto.org/docs/output-formats/all-formats.html) ·
Quarto logo: Posit, PBC]{.source}
::: {.notes}
Say this early: Quarto costs nothing and needs no licence key, for individuals, universities and
companies alike. The Quarto CLI is under the MIT License from version 1.4 (GNU GPL v2 before that),
and the tools it bundles have their own open-source licences
(https://quarto.org/license.html, checked 2026-11-06). The paid part of today is the coding
agent, a separate tool: the next slides come back to that. Pandoc converts the Markdown. Code cells run in Jupyter (Python) or knitr (R), and their
results are inserted. Quarto's principal languages are Python, R, Julia and Observable
JavaScript (`{ojs}` cells, run in the reader's browser); Jupyter kernels add many more,
such as MATLAB or Java (https://quarto.org/docs/faq/,
https://quarto.org/docs/computations/ojs.html). knitr's engines run `{sql}`, `{c}` and
`{bash}` cells (https://pkg.yihui.org/rmarkdown-book/language-engines.html); in Jupyter,
`!` lines run shell commands
(https://quarto.org/docs/computations/execution-options.html#shell-commands). Today we
use Python only. The official
list groups documents (HTML, PDF, MS Word, OpenDocument, ePub), presentations (Revealjs,
PowerPoint, Beamer), Markdown flavours, wikis and more (Jupyter, JATS, RTF, …):
https://quarto.org/docs/output-formats/all-formats.html. ePub is the e-book format:
https://quarto.org/docs/reference/formats/epub.html. Websites and blogs
(https://quarto.org/docs/websites/) and dashboards (https://quarto.org/docs/dashboards/)
are built from the same files. All checked 2026-10-30. The Quarto logo is a Posit, PBC
trademark, used here to refer to Quarto (https://quarto.org/trademark.html).
:::
## 🚫🤖 Quarto Is Not AI {#quarto-not-ai}
::: {.cards}
::: {}
[⚙️]{.big}
**Traditional software**
same input → same output, every time
:::
::: {.fragment}
[📚]{.big}
**Built for publishing**
quality documents, slides and websites
:::
::: {.fragment}
[🤖]{.big}
**The agent is separate**
it writes the files · Quarto turns them into formats
:::
:::
. . .
🔁 No AI inside Quarto: it follows your source exactly
::: {.notes}
Participants sometimes assume Quarto is an AI tool because the workshop uses a coding
agent. It is not: Quarto is open-source publishing software (built on Pandoc, with
Jupyter or knitr running code) that reads Markdown and code and writes the same outputs
every time for the same inputs and data. It does not generate text, code or figures by
itself and sends nothing to an AI service. The coding agent is a separate tool that
writes and edits the source files on request; Quarto then renders them. That split matters
for trust: the agent can make mistakes, so you check its files, while a render is
repeatable. Code cells you add run whatever code they contain, so if a cell calls an AI
service, that is your code, not Quarto. See https://quarto.org/ (not yet re-checked for
this slide).
:::
## 🔁 Reproducible: Same Source, Same Result {#reproducible}
::: {.cards .tips}
::: {}
[📄]{.big}
**One source**
text + code + data in plain files
:::
::: {.fragment}
[🧮]{.big}
**Numbers are computed**
never typed or pasted in
:::
::: {.fragment}
[▶️]{.big}
**One command**
`quarto render` rebuilds everything
:::
::: {.fragment}
[🕰️]{.big}
**Versioned with git**
every change saved · `uv.lock` pins the tools
:::
:::
. . .
✏️ Change one value in the data → render → **table, chart and sentence all update**
🏷️ `git` (set up next) records which version of the files produced which result
::: {.check}
💬 You correct one number in the data. What do you retype in the report?
:::
::: {.notes}
Reproducible means that someone else, or you in six months, can rebuild the same results
from the same files with one command, and that you can see where every number came from. It
is the reason for the workshop's structure. The report is source, not a pasted result: its
figures, tables and numbers in sentences are computed by code cells and inline code from
the data files, so changing an input and re-rendering updates every output without
retyping (the "change an input, rebuild, and explain what updated" outcome). Reproducibility
depends on versioning: git, the version control tool installed in Setup, saves a numbered
snapshot (a commit) of the source, data and settings together with a message saying what
changed and why. Any earlier snapshot can be restored, two versions compared, and a result
tied to the exact files that made it; without versions, "the same source" is whatever
happens to be on the disk today. GitHub then keeps a shared copy, and the same history
backs the AI usage statement: you can show what the agent changed and what you
reviewed. The project's `pyproject.toml` and `uv.lock` are versioned too: they pin the
Python packages, so a participant's machine and a colleague's give the same environment. This matters most with a coding agent: it may
write code that looks right and is not, so we ask it to compute from the data and then
render and check, and anyone can re-run the render to confirm. Reproducible does not mean
correct: a wrong analysis reproduces perfectly, so we still check results against their
sources. Good answer to the check: nothing; fix the data and re-render.
:::
# 🛠️ Setup {#setup}
[🏠 before the workshop]{.clock}
::: {.bigline}
🧭 6 steps, in order · ✅ the 🧪 test run says 42 = ready
:::
::: {.notes}
Pre-work, done at home before the day: this section holds only what installing needs, and the
reading follows in 📖 Read Before the Day. In the room, skip both 🏠 sections: the 0:15 block
starts at 🧰 Ready to Prompt (click its segment in the progress bar).
:::
## 🧭 Setup Map: 6 Steps {#setup-map}
[🏠 before the workshop]{.pace}
| 🧭 | Do this | ✅ It worked when |
|:-:|---|---|
| 1 | [🧰 Get your computer ready](#computer-ready) | `git --version` runs · 🪟 `wsl -l -v` shows VERSION 2 |
| 2 | [📁 Move around the terminal](#terminal-basics) | after `cd ~` the prompt shows `~` |
| 3 | [🧩 Install a coding agent](#install-assistant) | it starts, signed in |
| 4 | [🐧 Agent installs the tools](#install-tools) | it prints every version |
| 5 | [🛠️ Setup check](#setup-check) | every check says OK |
| 6 | [🧪 Test run](#test-run) | `hello.pdf` says 42 |
. . .
::: {.hint}
🧭 = do it · 📖 = just read · 🆘 stuck → AI chat, then Discord · ✅ all 6 done? [📖 Read before the day](#read-before)
🎒 **Have ready:** a free [GitHub account](https://github.com/signup) · a paid agent plan or API key · the Discord invite
:::
::: {.notes}
Participants said the setup slides were hard to follow, mostly on Windows (workshop of
2026-11-05): they could not tell which slides to do and which to read, or where they were.
So the six steps now run back to back. Before them come only the slides that prepare for
them (the connection, and where to get help); between them only 👀 What You Should See, the
screens step 3 ends on, and ⌨️ Two Places to Type, which step 4 needs; their pills say so. Everything else to read (how the agent works, models
and costs, the root folder, AI policy, Markdown) is in its own 🏠 section, 📖 Read Before the
Day, after the test run, so nobody installing pages past a price table. Every slide that must
be done carries a "🧭 Step n/6" pill and every reading slide a "📖" pill. Each row links to its
step, so someone returning after an error can find their place. Step 1 is one slide for every
system; Windows goes on to `windows-setup.qmd`, a separate page, because its procedure needs one
action at a time, a "you should see" after each, and a stuck-table, and Mac and Linux participants
no longer page through it. Each step has an observable check, which is the row's last column. Sign-up
and email checks can take hours, so the accounts come first. Ask Windows participants for
the `wsl -l -v` output before the day (step 1), since WSL needs an administrator account, a
restart and sometimes BIOS access.
:::
## 📶 You Need a Stable, Fast Internet Connection {#internet}
[🏠 before the workshop]{.pace} [📖 reading]{.pace}
::: {.cards .tips}
::: {}
[⬇️]{.big}
**Big downloads**
Ubuntu, Quarto, the agent, Python packages, data
:::
::: {.fragment}
[☁️]{.big}
**The agent is online**
every reply needs the connection · it stops when the Wi-Fi drops
:::
::: {.fragment}
[🏠]{.big}
**Do setup at home**
wired or strong Wi-Fi · avoid hotels, trains, firewalled work networks
:::
:::
. . .
🔌 Plugged in · 📵 No VPN or proxy if you can · 🧪 Test run done at home = ready
::: {.notes}
Almost every setup step downloads something: the Ubuntu image (several hundred megabytes),
Quarto, uv and the Python packages, the agent itself, and the workshop data. The coding
agent also sends every request to a model over the internet, so a poor connection shows
up as long pauses, timeouts and half-finished installs, which participants often take for
their own mistakes. Ask everyone to do the setup on a reliable connection, and to bring a
phone hotspot as a fallback. Company networks with a proxy or TLS inspection often block
downloads: raise it before the day. In the room, check that the venue Wi-Fi copes with every
participant downloading at once, and say what to do if it does not.
:::
## 🆘 Error? Ask an AI Chat {#ask-ai-chat}
[🏠 before the workshop]{.pace} [🆘 when stuck]{.pace}
::: {.cards .tips}
::: {}
[📋]{.big}
**Copy**
the command you ran + the **full** error text
:::
::: {.fragment}
[🌐]{.big}
**Paste into a web chat**
Gemini, Claude or ChatGPT in your browser, with your system (Windows + Ubuntu, or Mac)
:::
::: {.fragment}
[🔧]{.big}
**Try the fix**
one suggestion at a time · read it before you run it
:::
::: {.fragment}
[🔁]{.big}
**Still failing?**
paste the new error · then Discord `#help`
:::
:::
. . .
🔒 No passwords, keys or private data in the paste
::: {.notes}
Installs fail before the coding agent works, and sometimes the agent itself is what
fails, so the participant needs a second route that does not depend on it: a free web chat in
the browser (Gemini, Claude or ChatGPT). Good habits: paste the exact command and the whole
error, say the operating system (for WSL: Windows with Ubuntu on WSL), say what step of the
deck you are on, and try one suggested fix at a time. Read each command before running it:
a chat can be wrong, and never run a command that deletes things or asks for
administrator rights without understanding why. Remove passwords, tokens, API keys and
private data first (the AI-policy slide later explains why). If two suggestions fail, post the error and
what you tried in Discord. This is the same habit the workshop teaches with the agent:
you direct, check and take responsibility. The room rule remains: two minutes stuck, ask.
:::
## 💬 Discord: Our Workshop Room {#discord}
[🏠 before the workshop]{.pace} [💬 get help]{.pace}
::: {.cards .tips}
::: {}
[🔗]{.big}
**Join the server**
open the invite link from the organiser · pick a name we know
:::
::: {.fragment}
[#️⃣]{.big}
**Text channels**
one topic each, like `#help` · type, paste, share screenshots
:::
::: {.fragment}
[🔊]{.big}
**Voice channels**
click to join, click to leave · mute until you speak
:::
::: {.fragment}
[📣]{.big}
**Tag someone**
type `@` and their name · they get a notification
:::
:::
. . .
🆘 Stuck? Post in the help channel: what you ran, the error, a screenshot
::: {.notes}
Discord is where the organiser and participants talk during the workshop: questions, error
screenshots and links go in the text channels, and the voice channels are for the group and
for pairing. Send the invite link with the pre-work, and ask people to join before the day
so that problems with accounts or the app show up early. A server is the whole workshop
space; it holds channels. Text channels are named with a `#`, voice channels have a speaker
icon. Discord runs in the browser, as a desktop app and on a phone. Also useful: reply to a
message to answer it, add a reaction to say "seen" without noise, and mute channels you do
not need. When someone is stuck, ask for the exact command, the full error text and a
screenshot, and remember the room rule: two minutes stuck, then catch up. The organiser
supplies the real invite link and channel names for each run; this deck does not publish
a link.
:::
## 🔁 Discord ↔ WhatsApp {#discord-whatsapp}
[🏠 before the workshop]{.pace} [💬 get help]{.pace}
| 💬 Discord | 📱 WhatsApp |
|---|---|
| Server | Community |
| Text channel | Group chat |
| Voice channel | Group call you can join and leave |
| `@name` tag | `@name` mention |
| Reply to a message | Reply to a message |
| Direct message | Chat with one person |
| Invite link | Group invite link |
| Reaction | Reaction |
. . .
⚠️ Unlike a WhatsApp group, a Discord server has **many channels**: pick the right one
::: {.notes}
Use this for participants who know WhatsApp but not Discord. The mapping is approximate: a
server is closest to a WhatsApp Community, which also holds several groups, and a text channel
is closest to one group chat. A voice channel is always open: you join to talk and leave when
done, with no call to start or answer. Discord also has threads (a side conversation under
one message) and roles, which have no close WhatsApp equivalent. WhatsApp features and names
change, so check the right-hand column against the app before teaching.
:::
## 🧰 Get Your Computer Ready {#computer-ready}
[🏠 before the workshop]{.pace} [🧭 Step 1/6]{.pace} [do only your system's line]{.pillnote}
::: {.bigline}
🪟 **Windows** 👉 [**Open the Windows setup page**](windows-setup.qmd){target="_blank"}
:::
::: {.you .installers}
::: {}
**🍎 Mac**
:::
```bash
xcode-select --install
```
::: {}
**🐧 Ubuntu, Debian**
:::
```bash
sudo apt update && sudo apt install -y curl git
```
:::
::: {.hint}
🪟 9 short steps · 🛡️ admin account · 🔁 one restart: 📱 open it on your phone too
🍎 ⌘ Space, type `Terminal`, Enter · paste · click **Install** · wait
🐧 Ctrl+Alt+T · password stays hidden · other Linux: install `curl` and `git` your usual way
:::
### Exercise · ⏱️ 20 min
::: {.done}
`git --version` prints a version. 🪟 In Ubuntu, and `wsl -l -v` shows VERSION 2.
:::
::: {.notes}
Every system gets ready here, so nobody skips step 1. The commands install `git` and `curl`, which
the next steps assume. Windows is the big one, and participants found it the hardest at the
workshop of 2026-11-05. It lives on its own page, `windows-setup.qmd`, because a beginner needs one
action at a time and a "you should see" after each, in a page that scrolls, can be kept beside
the terminal, survives the restart on a phone, and is translated by the browser. The page opens
with the picture of Windows as a house and Ubuntu as a room inside it, then covers the WSL install
in an administrator PowerShell, the restart, the same command again in a normal window (distributions
are per user, so someone else's administrator password must not install it), the first Ubuntu
start, the `wsl -l -v` check, copy and paste, `sudo apt install curl git`, four habits, and the
stuck-table. The command runs twice because on current WSL, when a restart is needed, `wsl
--install` only enables Windows features and installs no distribution
(https://github.com/microsoft/WSL/blob/3.0.3/src/windows/common/WslClient.cpp#L557-L564, checked
2026-11-06). `--no-launch` keeps first-time setup out of the administrator PowerShell tab, whose
folder would be `/mnt/c/WINDOWS/system32`; the Start menu's Ubuntu opens in `~`. Without
administrator rights or BIOS access WSL cannot be installed: collect such participants before the
day and pair them with a neighbour (no native Windows route is supported).
On a Mac, the first `git` opens a dialog to install Apple's Command Line Tools
(https://git-scm.com/book/en/v2/Getting-Started-Installing-Git), so left alone it interrupts the
agent's install at step 4. `xcode-select --install` makes that a deliberate step at home
(https://docs.brew.sh/Installation, which also says Homebrew needs these tools only to build from
source). Quarto's Mac download is a standalone `.pkg` (https://quarto.org/docs/download/). All
checked 2026-11-06. Apple's own page could not be read by the check, and the dialog's wording
and download time are not documented here. "Already installed" from that command is fine: go
on. `sudo` asks for the Linux password, which stays hidden as you type. On other Linux, install
`curl` and `git` with its package manager. Written from documentation and not yet tried on a clean Mac or a Windows machine:
run both once before teaching.
:::
## 📁 Move Around the Terminal {#terminal-basics}
[🏠 before the workshop]{.pace} [🧭 Step 2/6]{.pace} [🚀 **Open it:** 🪟 Start → Ubuntu · 🍎 ⌘ Space → Terminal · 🐧 Ctrl+Alt+T]{.pillnote}
:::: {.columns}
::: {.column width="60%"}
```{=html}
<div class="terminal wsl basics" role="img" aria-label="A terminal session in Ubuntu on Windows. The prompt, ana@LAPTOP-4K7Q2PM:~$, shows the folder you are in. pwd prints /home/ana and date prints today's date and time. mkdir demo makes a folder and ls lists it. cd demo goes in, and the prompt now ends in ~/demo. mkdir notes and cd notes go one folder deeper, to ~/demo/notes, which pwd prints as /home/ana/demo/notes. cd .. goes up one folder, to ~/demo, cd ~ goes straight home, to ~, and rmdir demo/notes demo removes both empty folders.">
<div class="terminal-bar wt" aria-hidden="true"><b><i></i>Ubuntu</b><em>─ ▢ ✕</em></div>
<pre translate="no"><span class="pr">ana@LAPTOP-4K7Q2PM</span>:<span class="pa">~</span>$ <b>pwd</b>
<span class="out">/home/ana</span>
<span class="fragment"><span class="pr">ana@LAPTOP-4K7Q2PM</span>:<span class="pa">~</span>$ <b>date</b>
<span class="out">Sat Nov 7 09:14:52 -05 2026</span>
</span><span class="fragment"><span class="pr">ana@LAPTOP-4K7Q2PM</span>:<span class="pa">~</span>$ <b>mkdir demo</b>
</span><span class="fragment"><span class="pr">ana@LAPTOP-4K7Q2PM</span>:<span class="pa">~</span>$ <b>ls</b>
<span class="pa">demo</span>
</span><span class="fragment"><span class="pr">ana@LAPTOP-4K7Q2PM</span>:<span class="pa">~</span>$ <b>cd demo</b>
</span><span class="fragment"><span class="pr">ana@LAPTOP-4K7Q2PM</span>:<span class="pa">~/demo</span>$ <b>mkdir notes</b>
</span><span class="fragment"><span class="pr">ana@LAPTOP-4K7Q2PM</span>:<span class="pa">~/demo</span>$ <b>cd notes</b>
</span><span class="fragment"><span class="pr">ana@LAPTOP-4K7Q2PM</span>:<span class="pa">~/demo/notes</span>$ <b>pwd</b>
<span class="out">/home/ana/demo/notes</span>
</span><span class="fragment"><span class="pr">ana@LAPTOP-4K7Q2PM</span>:<span class="pa">~/demo/notes</span>$ <b>cd ..</b>
</span><span class="fragment"><span class="pr">ana@LAPTOP-4K7Q2PM</span>:<span class="pa">~/demo</span>$ <b>cd ~</b>
</span><span class="fragment"><span class="pr">ana@LAPTOP-4K7Q2PM</span>:<span class="pa">~</span>$ <b>rmdir demo/notes demo</b>
<span class="pr">ana@LAPTOP-4K7Q2PM</span>:<span class="pa">~</span>$ <span class="cursor">▊</span></span></pre>
</div>
```
:::
::: {.column width="40%"}
::: {.hint}
📍 `pwd` where am I?
📅 `date` today
👀 `ls` what is here?
🆕 `mkdir name` make a folder
🚪 `cd name` go in · ⬆️ `cd ..` up one
🏠 `cd ~` home, from anywhere
🗑️ `rmdir name` delete folder
:::
### Exercise · ⏱️ 4 min
::: {.done}
you typed these, `rmdir` raised no error, and the prompt shows `~`.
:::
:::
::::
[👀 Watch, then type the bold words, Enter after each · `~` = your home folder · 🍎 Mac: `ana@mac ~ %`, last folder only]{.source}
::: {.notes}
Everyone, on every system: the rest of the workshop happens in a terminal, a window where you
type commands instead of clicking. The picture is Ubuntu on Windows (WSL) in Windows Terminal,
where Windows 11 opens 🪟 Start → Ubuntu; Windows 10's plainer window, a Mac or a Linux terminal
look different but answer the same.
The terminal opens in your home folder, written `~` (here `/home/ana`; on a Mac `/Users/ana`).
`pwd` prints the current folder, `date` the day and time (`-05` is the time zone, as in
Colombia), `ls` lists the folder (Ubuntu shows folders in blue), `mkdir name` creates a folder,
`cd name` enters it, `cd ..` goes up one level and `cd ~` (or `cd` alone) goes straight home
from anywhere. The bold words are what you type. The part up to `$`, the prompt, is the terminal
saying who and where you are and that it is ready: `ana` is the Linux user, `LAPTOP-4K7Q2PM` the
Windows computer's name (yours differs), and the folder after the colon changes with every `cd`:
`~/demo`, `~/demo/notes`, back to `~/demo`, then `~`. The other lines are the answers. The
example is a picture of a session, so it cannot be selected or copied: typing it is the
exercise. On a Mac the prompt is `ana@mac ~ %`, ending in `%`, not `$`: same meaning; it shows
only the last folder, with no colon (`ana@mac demo %`, `ana@mac notes %`), and `pwd` gives the
full path. Tab
completes names, and the up arrow recalls the previous command: both save typing mistakes, so
show them. Type these rather than pasting them: the hands remember. Later slides ask you to run
`mkdir -p london-guide && cd london-guide`: this is that (`-p` makes no fuss if the folder
exists, `&&` means "and then, if that worked"). Ask while they type: after `cd ..`, what would
`pwd` print? Good answer: `/home/ana/demo`. Do the exercise from the home folder, where the
terminal opens. `rmdir name` removes an empty folder (it refuses if anything is inside, which is
the safe behaviour); `rmdir demo/notes demo` at the end removes both, inner one first, so the
exercise can be repeated.
:::
## 🧩 Install a Coding Agent {#install-assistant}
[🏠 before the workshop]{.pace} [🧭 Step 3/6]{.pace} [🪟 in Ubuntu · 🍎 `claude` not found? Paste the fix it printed, then a new tab]{.pillnote}
::: {.you .installers}
::: {}
**✳️ Claude Code** · [setup](https://code.claude.com/docs/en/setup)
:::
```bash
curl -fsSL https://claude.ai/install.sh | bash
```
::: {}
**🌀 Codex** · [guide](https://learn.chatgpt.com/docs/codex/cli)
:::
```bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh
```
::: {}
**♊ Antigravity** · [docs](https://antigravity.google/docs/getting-started?tab=cli)
:::
```bash
curl -fsSL https://antigravity.google/cli/install.sh | bash
```
:::
::: {.hint}
1️⃣ **Pick one:** paste its line, press Enter · 2️⃣ **New tab:** 🪟 Ctrl+Shift+D · 🍎 ⌘T · 🐧 Ctrl+Shift+T
3️⃣ **Start it:** `mkdir -p ~/setup && cd ~/setup`, then `claude`, `codex` or `agy` · trust this folder? ↓ to Yes, then Enter ([👀 screens](#assistant-screens))
4️⃣ **Sign in:** no browser? Copy the link it prints, whole, into yours · a code appears? Paste it back here
:::
### Exercise · ⏱️ 5 min
::: {.done}
the agent answers when you type `hello`. Then type `/exit`.
:::
::: {.notes}
Do this before the workshop. `curl ... | bash` downloads the vendor's small install script and
runs it: only do this with links you trust, here each vendor's own documented command. A new
tab is needed because a terminal learns where programs are when it starts, so it cannot find
one installed a moment ago; that is the usual `command not found` straight after an install. On
a Mac a new tab is not enough for Claude Code: its installer leaves `~/.local/bin` off the PATH
and prints the fix under "Setup notes" (https://code.claude.com/docs/en/troubleshoot-install,
checked 2026-11-06). Starting in `~/setup` means the first "trust this folder?" answer is safe;
📂 Your Root Folder, in 📖 Read Before the Day, explains why. Sign-in without a browser, as in WSL, ends with a code to paste back
at `Paste code here`; if pasting does nothing, right-click or Shift+Insert (same page).
Sign in with an account that has access to the tool: Claude
Code needs a Pro, Max, Team, Enterprise or Console account (https://code.claude.com/docs/en/setup),
Codex a ChatGPT sign-in or an API key (https://learn.chatgpt.com/docs/auth), Antigravity a
Google account. WSL cannot open a browser: Claude Code and Antigravity print a URL, which you
copy into the Windows browser, then paste the code back; if Codex's browser sign-in fails,
`codex login --device-auth` (first enable device codes in ChatGPT security settings).
Sign-up and email verification can take hours, so do not leave them for the day. Account
and sign-in details checked 2026-11-03; they change often, so re-check them before teaching.
Claude Code installer: https://code.claude.com/docs/en/setup. Codex standalone installer
for macOS and Linux: https://learn.chatgpt.com/docs/codex/cli, which also lists Windows,
`npm install -g @openai/codex` and Homebrew. Google's Antigravity CLI (`agy`):
https://antigravity.google/docs/getting-started?tab=cli, which also lists PowerShell and
CMD installers for Windows. It replaced Gemini CLI for unpaid-tier and Google One users on
18 June 2026 (https://www.geminicli.com/docs/get-started/installation); existing Gemini CLI
settings are migrated on first launch (https://antigravity.google/docs/cli/gcli-migration/).
All checked 2026-10-30. Start the agent inside the exercise folder, and never run two
agents writing to one folder.
:::
## 👀 Started? What You Should See {#assistant-screens}
[🏠 before the workshop]{.pace} [🧭 Step 3/6, screen by screen]{.pace}
```{=html}
<div class="screens">
<div class="r-stack">
<div class="terminal wsl fragment fade-out" data-fragment-index="1" role="img" aria-label="Ubuntu's terminal: mkdir -p ~/setup and cd ~/setup make and enter a new folder, then the prompt in ~/setup has claude typed.">
<div class="terminal-bar wt" aria-hidden="true"><b><i></i>Ubuntu</b><em>─ ▢ ✕</em></div>
<pre translate="no"><span class="pr">ana@LAPTOP-4K7Q2PM</span>:<span class="pa">~</span>$ <b>mkdir -p ~/setup && cd ~/setup</b>
<span class="pr">ana@LAPTOP-4K7Q2PM</span>:<span class="pa">~/setup</span>$ <b>claude</b><span class="cursor">▊</span></pre>
</div>
<div class="terminal wsl fragment fade-in-then-out" data-fragment-index="1" role="img" aria-label="Claude Code's sign-in screen. Select login method: 1, Claude account with subscription, which is selected; 2, Anthropic Console account, API usage billing; 3, 3rd-party platform.">
<div class="terminal-bar wt" aria-hidden="true"><b><i></i>✳️ Claude Code</b><em>─ ▢ ✕</em></div>
<pre translate="no"><span class="cc">Welcome to Claude Code</span> <span class="dim">v2.1.319</span>
<b>Claude Code can be used with your Claude</b>
<b>subscription or billed based on API usage through</b>
<b>your Console account.</b>
Select login method:
<span class="sel">❯ <span class="dim">1.</span> Claude account with subscription ·</span> <span class="dim">Individual,</span>
<span class="dim">Team, or Enterprise</span>
<span class="dim">2.</span> Anthropic Console account · <span class="dim">API usage billing</span>
<span class="dim">3.</span> 3rd-party platform · <span class="dim">Amazon Bedrock, Microsoft</span>
<span class="dim">Foundry, Google Vertex AI</span></pre>
</div>
<div class="terminal wsl fragment fade-in-then-out" data-fragment-index="2" role="img" aria-label="Claude Code asks about the new folder. Accessing workspace: /home/ana/setup. Quick safety check: Is this a project you created or one you trust? Claude Code'll be able to read, edit, and execute files here. Two choices: No, exit, which is selected, and Yes, I trust this folder. Enter to confirm, Esc to cancel.">
<div class="terminal-bar wt" aria-hidden="true"><b><i></i>✳️ Claude Code</b><em>─ ▢ ✕</em></div>
<pre translate="no"><span class="warn">────────────────────────────────────────────────────</span>
<b class="warn"> Accessing workspace:</b>
<b> /home/ana/setup</b>
Quick safety check: Is this a project you created
or one you trust? (Like your own code, a
well-known open source project, or work from your
team). If not, take a moment to review what's in
this folder first.
Claude Code'll be able to read, edit, and execute
files here.
<span class="dim"> Security guide</span>
<span class="sel"> ❯ No, exit</span>
Yes, I trust this folder
<span class="dim"> Enter to confirm · Esc to cancel</span></pre>
</div>
<div class="terminal wsl fragment fade-in" data-fragment-index="3" role="img" aria-label="Claude Code ready for a prompt. Claude Code version 2.1.319, the model and plan of the signed-in account, and the folder ~/setup. Below, the input line between two rules, with a grey suggestion: Try write a test for a file path.">
<div class="terminal-bar wt" aria-hidden="true"><b><i></i>✳️ Claude Code</b><em>─ ▢ ✕</em></div>
<pre translate="no"> <b>Claude Code</b> <span class="dim">v2.1.319</span>
<span class="cc"> ▐▛███▛█</span> <span class="dim">Opus 5.5 with xhigh effort</span>
<span class="cc">▝▜██████▀</span> <span class="dim">Claude Max</span>
<span class="cc"> ▝▝ ▝▝</span> <span class="dim">~/setup</span>
<span class="dim">────────────────────────────────────────────────────</span>
❯ <span class="dim">Try "write a test for <filepath>"</span>
<span class="dim">────────────────────────────────────────────────────</span></pre>
</div>
</div>
<div class="r-stack">
<div class="terminal wsl fragment fade-out" data-fragment-index="1" role="img" aria-label="Ubuntu's terminal: mkdir -p ~/setup and cd ~/setup make and enter a new folder, then the prompt in ~/setup has codex typed.">
<div class="terminal-bar wt" aria-hidden="true"><b><i></i>Ubuntu</b><em>─ ▢ ✕</em></div>
<pre translate="no"><span class="pr">ana@LAPTOP-4K7Q2PM</span>:<span class="pa">~</span>$ <b>mkdir -p ~/setup && cd ~/setup</b>
<span class="pr">ana@LAPTOP-4K7Q2PM</span>:<span class="pa">~/setup</span>$ <b>codex</b><span class="cursor">▊</span></pre>
</div>
<div class="terminal wsl fragment fade-in-then-out" data-fragment-index="1" role="img" aria-label="Codex's sign-in screen. Choose how you want to use Codex: 1, Sign in with ChatGPT, which is selected; 2, Sign in with Device Code, from another device with a one-time code; 3, Sign in another way, with an API key or another provider. Press enter to continue.">
<div class="terminal-bar wt" aria-hidden="true"><b><i></i>🌀 Codex</b><em>─ ▢ ✕</em></div>
<pre translate="no"> Welcome to <b>Codex</b>, OpenAI's command-line coding
agent
Choose how you want to use Codex.
<span class="cy"><span class="faint">> 1. </span>Sign in with ChatGPT</span>
<span class="cy faint"> Usage included with Plus, Pro, Business, and</span>
<span class="cy faint">Enterprise plans</span>
2. Sign in with Device Code
<span class="dim"> Sign in from another device with a one-time</span>
<span class="dim">code</span>
3. Sign in another way
<span class="dim"> Use an API key or another provider</span>
<span class="dim"> Press </span><b>enter</b><span class="dim"> to continue</span></pre>
</div>
<div class="terminal wsl fragment fade-in-then-out" data-fragment-index="2" role="img" aria-label="Codex asks only in a folder that is a git repository, here /home/ana/london-guide. Folder access. Trust this folder? Codex can read, edit, and run files here, subject to your permission settings. Two choices: 1, Trust and continue, which is selected, and 2, Back to Agent Command Center. Enter continue, Esc back.">
<div class="terminal-bar wt" aria-hidden="true"><b><i></i>🌀 Codex · in a git folder</b><em>─ ▢ ✕</em></div>
<pre translate="no">
<b> Folder access</b>
<span class="dim"> /home/ana/london-guide</span>
Trust this folder? Codex can read, edit, and run
files here, subject to your permission settings.
Folder settings can run code automatically, even
without a model request. Continue only if you
trust these files. Your trust decision will be
saved.
<b class="rev">› 1. Trust and continue</b>
2. Back to Agent Command Center
<b>enter</b><span class="dim"> continue · </span><b>esc</b><span class="dim"> back</span></pre>
</div>
<div class="terminal wsl cxwin fragment fade-in" data-fragment-index="3" role="img" aria-label="Codex ready for a prompt. OpenAI Codex version 0.167.0, folder ~/setup, a faint logo, the input line Ask Codex to do anything, and below it the model Sol on low effort, the folder, and the hints: left arrow for agents, question mark for shortcuts.">
<div class="terminal-bar wt" aria-hidden="true"><b><i></i>🌀 Codex</b><em>─ ▢ ✕</em></div>
<div class="cxhome" translate="no">
<div><span class="cx">>_</span> <b>OpenAI Codex</b> <span class="dim">(v0.167.0)</span><br><span class="dim"> ~/setup</span></div>
<div class="cxlogo" aria-hidden="true">◎</div>
<div class="cxprompt">› <span class="dim">Ask Codex to do anything</span></div>
<div class="cxfoot"><span class="gold">Sol low</span><span class="dim"> · </span><span class="grn">~/setup</span><br>← <span class="dim">for agents ·</span> ? <span class="dim">for shortcuts</span></div>
</div>
</div>
</div>
</div>
```
::: {.r-stack .screen-hints}
::: {.hint .fragment .fade-out fragment-index=1}
⌨️ **Start:** in the terminal, type the bold words, then Enter · ✳️ first asks for a text style: Enter · ➡️ each next screen
:::
::: {.hint .fragment .fade-in-then-out fragment-index=1}
🔑 **Sign in:** Enter on `1.` · no browser? Copy the link it prints, whole, into yours · 🌀 or `2.`, a code
:::
::: {.hint .fragment .fade-in-then-out fragment-index=2}
🛡️ **Trust:** ✳️ ↓ to `Yes, I trust this folder`, then Enter · quit by mistake? Type `claude` again · 🌀 not in `~/setup`: later, in a git folder
:::
::: {.hint .fragment .fade-in fragment-index=3}
✅ **Ready:** type `hello`, then Enter, and it answers · `/exit` quits
:::
:::
::: {.notes}
Step 3 screen by screen: each → shows the next screen in both windows, and the box below says
what to press. The windows are drawn as Ubuntu on Windows (WSL) in Windows Terminal, like 📁
Move Around the Terminal; the screens inside are the same on a Mac or Linux. Captured on
2026-11-07 from Claude Code 2.1.319 and codex-cli 0.167.0 on macOS, each started in a new,
empty folder in a 52-column terminal, with no prompt sent. Sign-in is a first start with an
empty settings folder (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`); Claude Code first asks for a text
style (Dark mode is selected, so Enter), and its animated banner above the sign-in choices is
cut. Option 1 is the subscription sign-in in both: it opens the browser, or, where there is
none, as in WSL, prints a link to copy into the browser. Codex's option 2, a device code, is
the fallback when the browser sign-in fails. Trust: Claude Code asks about every new folder,
and its pointer starts on "No, exit", so pressing Enter straight away quits: press ↓ first.
Quitting is harmless: start it again. Codex asked nothing in a plain folder such as `~/setup`;
in a new git repository it showed "Folder access" with "1. Trust and continue" selected
(shown with the path changed to `/home/ana/london-guide`), so Codex users meet the question
later, in a project that is a git repository. Ready: the lines beside Claude Code's logo name
the signed-in account's model and plan (here the capturing account's: Opus 5.5, Claude Max);
yours will differ. Only folder paths are changed, to `/home/ana/...` and `~/setup`; the empty
rows above each input line and the status lines below it (model, effort, permission mode) are
cut. The `ana@LAPTOP-4K7Q2PM` prompt in the first screen is drawn, not captured. Antigravity (`agy`) is not
shown. Screens change between versions: re-capture them before each run. 📂 Your Root Folder,
in 📖 Read Before the Day, explains what trusting a folder allows.
:::
## ⌨️ Two Places to Type {#two-places}
[🏠 before the workshop]{.pace} [📖 read before step 4]{.pace}
:::: {.columns}
::: {.column width="49%"}
::: {.you}
**🖥️ The terminal** · its line ends in `$` (🍎 `%`)
```{=html}
<div class="terminal mini" role="img" aria-label="A terminal prompt, with pwd typed after it."><pre translate="no"><span class="pr">ana@laptop:~/setup$</span> <b>pwd</b></pre></div>
```
commands: `pwd`, `cd`, `quarto preview`
:::
:::
::: {.column width="49%"}
::: {.prompt}
**🤖 The agent** · it runs inside the terminal
`> Which tools are missing?`
plain language, and `/` commands: `/exit`
:::
:::
::::
. . .
🚪 **In:** type `claude` · **Out:** type `/exit` · box colours say which place
::: {.hint}
➕ Agent busy and a green box to do? Second tab: 🪟 Ctrl+Shift+D · 🍎 ⌘T · 🐧 Ctrl+Shift+T
😌 Wrong place? Usually harmless: `command not found`, or the agent just reads it
:::
::: {.check}
💬 The agent is running and a slide says to type `gh auth login`. Where do you type it?
:::
::: {.notes}
This is the mix-up that costs beginners the most time, so it gets its own slide before the
first prompt. The agent takes over the terminal tab while it runs: what you type goes to
it, not to the shell, until `/exit`. Green "You type" boxes go in the terminal; violet "Ask