Session record: 2026-09-27

This file is a chronological record of one working session between the owner and Claude Code. The session started with the first split of the documents. It ended with a plan for Assembly and Fortran demos that run in a web browser. Each round gives the request, the work that Claude Code did, and the result. The decisions are in ../DECISIONS.md. The roadmap that came from the session is in ../PLAN.md.

Round 1: split the documents into segments

• Request: split the documents into as many document parts (segments) as possible, in a subfolder. The goal: an adversarial review (a review that tries to find faults) of each document part against its goals and objectives.
• Done:
  • Claude Code wrote split_documents.py.
  • The script split the Markdown reports at every heading. The parts: the title and opening paragraph, the introduction text of each section, each subsection, and the works cited.
  • The script split the HTML advisors at each <section>. Each part got the section text, its raw HTML, and the JavaScript that it uses. That JavaScript is the quiz scoring, the roadmap data, and the chart numbers.
  • Each document part got a front-matter header (the source and the line range) and an empty review worksheet.
• Result: 56 document parts (22 + 20 + 7 + 7). Each Markdown source line is in exactly one document part.
  • A slug bug made the HTML folder names too short. Claude Code repaired it.
  • Known limit: the script cannot link the inline citation numbers of the reports to their sources automatically.

Round 2: first-pass adversarial review

• Request (after the owner moved all files into review/): review all four documents and write a first pass of adversarial reviews.
• Done:
  • Claude Code read all four documents fully.
  • It decoded the salary figures that exist only in embedded images. Two ranges are cut short ("$112,000 –", "$105,000 –").
  • It read the scripts of the two HTML pages. The quiz shows a verdict after one answer, because the code never uses answeredCount. Also, option A is always Assembly.
  • It counted the citations:
    • Report 02: 42 of about 81 citations point to one Reddit thread. Its bibliography looks like a copy of the bibliography of report 01.
    • Report 01: about 28 of its 56 listed sources have no citation in the text.
• Result: review/adversarial-review-pass1/, with four reviews and a summary.
  • Goal met? 01 Partly · 02 No · 03 No/Partly · 04 No.
  • Primary problems:
    • Report 01 gives a Freelancer page as the source for a LANL report.
    • Report 02 bases its case for Fortran on features that did not exist on DOS in the 80s and 90s (FORTRAN 77 array syntax, SIMD, an FPU).
    • History does not agree with the genre mapping of report 02 (Elite, Frontier, M.U.L.E.).
    • “Locked 60 fps” is not possible in single-page Mode 13h at 70 Hz.
    • Neither report considers the C language.
  • Claude Code did not fetch the sources. Thus the [KNOW] and [VERIFY] findings are provisional.

Round 3: “document this first”

• Done: review/README.md. It tells about the documents, the layout, the method, the evidence tags, the results, the next steps, and the log.
• Claude Code removed a remaining __pycache__ folder that the review made.

Round 4: map the review onto document parts, and make a website

• Request: compare the document parts with the review, and use the review to divide its findings among the document parts. Also recommend a method to make a static website for GitHub Pages (free web hosting from GitHub) with interactive features. The owner added this instruction during the round: put the generated pages in serve/.
• Found: the owner moved the source documents into review/segments/. The first run found no documents and wrote over only generated files. Claude Code then changed the script to use the new location.
• Done:
  • Claude Code put the 61 findings into review/findings/pass1.json. From then on, this file was the source of truth.
  • The splitter script now uses the line ranges to connect each finding to a document part. It writes a findings table into each document part. It also makes manifest.json and review/findings/segment-map.md.
  • The comparison showed these results:
    • No finding crosses a document-part boundary badly. The only two findings outside all document parts are about <head> scripts.
    • The findings collect in three areas. These are the Fortran-technical and labour-market parts of doc 01, the verdict parts of doc 02, and the quiz and chart parts of the HTML pages.
    • 15 document parts have no challenge yet.
  • Claude Code wrote site/build.py, a Python builder. It uses the markdown package through uv. Claude Code selected it, not MkDocs or a similar tool, because the tracker needs a custom findings table and heatmap. The builder makes:
    • a dashboard with progress cards, a scorecard, and a heatmap of the document parts,
    • a findings explorer with filters, search, sorting, and URLs that the owner can share. The explorer keeps status and note changes in the browser and can export them as “status.json”.
    • pages for each document part, each review, and each source (copies of the original HTML advisors, so that their quizzes still work),
    • site search and a light/dark theme.
  • Claude Code examined the site in Chrome. All 1,107 internal links work, the interaction tests pass, and there are no console errors. It also repaired Markdown asterisks that showed in the findings table.
• Result: 70 HTML pages in serve/. Also a GitHub Actions workflow (a service that runs build jobs on GitHub) to publish them.

Round 5: make a public GitHub repository and turn on Pages

• Request: make a public repository with gh (the GitHub command-line tool) and turn on Pages. If necessary, add gh permissions, but do not remove permissions.
• Done:
  • gh already had the repo and workflow permissions. Thus Claude Code added nothing.
  • A scan for secrets found nothing. The commits use the GitHub no-reply email.
  • Claude Code made kairin/000-111-learn and pushed it.
  • It turned on Pages with the “GitHub Actions” source. The deployment was successful.
• Result: the site is live at https://kairin.github.io/000-111-learn/. Claude Code added the URLs to the README.

Round 6: do not use GitHub Actions, but build the site again automatically at each commit and push

• Request: use no remote Actions. Each commit and each push must build the site again on the local computer and include it.
• Done:
  • Claude Code made the build give identical output for identical input. There is no timestamp, the inputs are sorted, markdown is fixed at version 3.11, and there is an --out option. A test build from two locations gave identical results.
  • It wrote site/regenerate.sh. The script takes a copy of the staged files, splits the document parts again, and builds the site again. Then it stages only the generated files.
  • It added Git hooks (scripts that Git runs at a commit or a push) in .githooks/, turned on with core.hooksPath:
    • pre-commit runs the regenerate script. If the build fails, it stops the commit.
    • pre-push copies the serve/ folder of the pushed commit to the gh-pages branch and pushes it.
  • It removed the Actions workflow.
  • It made a commit. The hook did a test on itself during that commit.
• Question from the owner during the round: “why not use something that builds it effectively and efficiently?” The answer:
  • The build takes about one second, so speed is not the problem.
  • The steps come from the two requirements (build on the local computer, keep the site in serve/). All builders need these steps.
  • Claude Code gave options A to E. It recommended a new name for serve/: docs/.

Round 7: “why are these issues?”

• The first paste in this round had text from a different session (a task board with “0 of 270 cards”). Claude Code did not use that text. The owner then pasted the correct part.
• Answer: the steps are not problems. They are the usual steps of a local build, and Claude Code made them sound more serious than they are. Also, GitHub Actions runners (the GitHub computers that run the jobs) are free at this time for public repositories.
• Done: Claude Code pushed the hook setup. The pre-push hook made and pushed gh-pages. Claude Code changed Pages to publish from gh-pages / (root). It made sure that the live site was the version from the local build.

Round 8: use Actions again. Which tools can show data and interactive features?

• Request: the repository is public, so use GitHub Actions. Which tools can show data and interactive features on static pages?
• Answer:
  • Claude Code compared Astro + Starlight, Observable Framework, Quarto, Evidence, MkDocs Material/Zensical, Hugo, and the current builder.
  • It recommended Astro + Starlight for this mix of many documents and data pages.
  • It proposed an “Edit on GitHub” link on each finding to track its status.
• Not done yet: Claude Code waited for the owner to select the tool.

Round 9: run Assembly or Fortran interactively in the browser

• Question: if the interactive parts are in Assembly or Fortran, how do they run on a static page?
• Answer:
  • They use WebAssembly (Wasm, a code format that browsers run). The Actions build compiles the code, and the browser of the visitor runs it.
  • Fortran: the Wasm backend of LFortran, LLVM Flang with Emscripten, or f2c with Emscripten for FORTRAN 77.
  • Assembly: NASM makes DOS programs that run in js-dos (or v86 for a full PC). Other options: hand-written WebAssembly text, or an assembler and an emulator in the page (RISC-V or 6502).
  • Limits: multithreaded Wasm on GitHub Pages needs the coi-serviceworker workaround. Emulators add a few MB.
  • Claude Code suggested two proof-of-concept demos. The first is a Fortran heat-equation kernel with a slider and a chart. The second is a NASM Mode 13h program in js-dos.

Round 10: this record

• Request: add the browser-run code to the learning plan in the repository. Also record the full conversation and list the decisions that are still open.
• Done: ../PLAN.md, ../DECISIONS.md, and this file. Also links from review/README.md and a top-level README.md for GitHub.

Round 11: goal decided, and move the site to Astro + Starlight on GitHub Actions

• Decisions of the owner (made during the round):
  • O1: “I want to learn both. No financial gain… it will be fun to have a super constrained game developed, which somehow can be played on a static website via gh pages.” → D11.
  • O2: Astro + Starlight, agreed → D12.
  • O3: move the site first and make it work with GitHub Pages Actions → D13.
• Done:
  • Claude Code removed the local hooks, the old Python builder, and the committed serve/. It also removed the core.hooksPath setting.
  • It made site/ as an Astro 7.3 + Starlight 0.42 project. The script scripts/sync-content.mjs changes review/ into Starlight pages with new links. It also copies the original HTML pages and writes the data for the dashboard and the findings.
  • It made the dashboard again as a Starlight page (cards, scorecard, heatmap, checklist, log).
  • It made the findings explorer again as a Starlight page. The explorer has filters, search, sorting, URLs to share, and drafts in the browser. It also has “Copy status.json” and an “Edit on GitHub” link to review/findings/status.json.
  • It added an Actions workflow. The workflow splits the document parts again, builds with Astro, and publishes serve/.
  • It changed the sidebar configuration for the change in Starlight 0.39.
  • Local checks: 74 pages, 0 broken internal links, the explorer interactions pass in Chrome, and no console errors.
• Planning:
  • Claude Code wrote ../PLAN.md again around “learn both via one constrained game”.
  • New open decision O7: how the two languages share the game. The recommendation is C. The game is in x86 assembly and runs in js-dos. Modern Fortran is the lab for tables, reference checks, and a Wasm physics page.
  • New open decision O8: the game concept and constraints. The recommendation is an orbital lander on VGA Mode 13h, then Mode X.

Round 12: better Facebook link previews

• Request: make Facebook show a good preview when a person shares https://kairin.github.io/000-111-learn/.
• Found: Starlight already wrote og:title, og:description, and og:url, but no og:image. These are Open Graph tags (page data that Facebook reads for a preview). The preview title of the homepage was only “Review dashboard”.
• Done:
  • At each build, site/scripts/og-image.mjs uses sharp to make a 1200×630 PNG. The image shows the title, the live statistics, and a small copy of the heatmap of the document parts.
  • Each page now has og:image (with width, height, type, and alt text) and twitter:image.
  • The homepage replaces its title, og:title, og:type (website), and og:description.
• Added request (during the round): each commit and push must also refresh the Facebook preview.
  • Done: the image link now includes the commit ID (?v=<commit>). A new workflow job, refresh-link-previews, runs after each deployment. It asks the Facebook Graph API to read the homepage, findings, and plan pages again.
  • For this, Facebook requires an app access token. The job reads the token from the repository secret FACEBOOK_APP_TOKEN. If the secret is not there, the job skips this step without an error.
• Still necessary from the owner: make a Facebook developer app and store <app-id>|<app-secret> with gh secret set FACEBOOK_APP_TOKEN. Until then, use Scrape Again in the Sharing Debugger manually.

Round 13: the language lens, A side and B side, and the STE writing standard

• What the owner said: the four Gemini documents are not the central concern. They only helped to make the idea. The adversarial review is not the primary objective either. It helps to find areas that the owner did not think of. The owner is not a developer. Reading English is the bridge to the two languages.
• The lens (D16): vocabulary as parts of speech. Assembly verbs are instructions, and its nouns are registers and memory. Fortran verbs are statements, and its adjectives are attributes (ALLOCATABLE). Its idioms are built-in functions (MATMUL), and its grammar is maths notation. The owner said that this “resonated very strongly”.
• Malay is the mother tongue of the owner, and English is the language of thought. Assembly is the first language of the machine, like the Rumi script for machine code. Fortran speaks maths (FORmula TRANslation).
• Vocabulary counts (examined in the sources): the original 8086 list has 81 instructions and 14 register names (Wikipedia, List of x86 instructions). With jump variants and synonyms, there are 118 written forms. Fortran 2018 has 598 keywords: 127 statements, 45 attributes, and 275 built-in procedures (cdslaborg/FortranKeywords, MIT license).
• Writing standard (D17): all documents use ASD-STE100 Simplified Technical English from /home/kkk/Apps/ASD-STE100. The owner asked for a global setup for each Claude Code session on this computer. The setup has three parts:
  • the skill ~/.claude/skills/ste-writing/ (links to the repository),
  • the rule ~/.claude/CLAUDE.md,
  • a PostToolUse hook ~/.claude/hooks/ste-lint.sh in ~/.claude/settings.json (backup settings.json.bak-2026-09-27).
• A live test showed that the hook reports a high score to Claude after a write. The ASD-STE100 AGENTS.md also has workspace-setup steps (clone more repositories, run a dotfiles script). These steps did not run, because the owner did not ask for them.
• Rewrites: five helper agents wrote the pass-1 reviews and the summary again in STE. All IDs, line cells, and facts stayed the same. The findings text in pass1.json came again from the new reviews. The line ranges and statuses did not change.
• New content in learn/: start-here.md (the bridge from reading English), a-side.md, b-side.md, segments.json (seven segments with strengths, limits, examples, and related findings), parts-of-speech.json, and the two dictionaries vocabulary/assembly.json and vocabulary/fortran.json.
• New site structure (D18): the home page shows the two sides and the lens. Each segment has an A page and a B page. Each page has strengths, limits, one example sentence, the words by part of speech, and “Watch out” notes from the review.
  • A dictionary page has filters and search.
  • A compare page shows the sizes of the two dictionaries.
  • The review moved to “Background research”, and its dashboard moved to /review/.
  • The review “segments” are now “document parts” on the site, so that “segment” has one meaning.
  • A new link-preview image shows the A side and the B side.
• Checks: 94 pages, no broken links, the dictionary filter works in Chrome, and no console errors.

Round 14: the two open decisions, and the first test of the game

• What the owner said: “okay with your proposal for now”. This accepted the two recommendations.
  • D19 (was O7): split roles. The game is 8086 Assembly in js-dos. Modern Fortran is the laboratory.
  • D20 (was O8): a small lander game, on an 8086 or 386 PC with VGA Mode 13h, then Mode X, at 70 or 35 frames each second.
• The first test: a new folder game/.
  • The B side (lab/sine_table.f90) makes 256 sine values as whole numbers.
  • The A side (src/spike.asm) draws the curve and moves a yellow dot along it. It is 655 bytes, with 8086 instructions only (cpu 8086).
  • The test (test/check.asm) runs the same routine (src/sine_y.inc) in DOSBox without a screen. The checker (lab/check_y.f90) agrees on 256 of 256 values. The largest difference from exact maths is 1 pixel.
  • A deliberate change of one value made the check fail (exit code 1). Thus, the check can catch an error.
• Build: this computer has no Fortran compiler, no assembler and no DOSBox, and installation needs a password. Thus, game/dev.sh runs game/build.sh in an Ubuntu 24.04 container (Docker). GitHub Actions runs the same script on Ubuntu 24.04. If the check fails, nothing is published.
• The website: a new page /game/ shows the program in js-dos 8.4.1. The site keeps its own copy of the js-dos files, with the GPL-2.0 license and a notice. The player is in an iframe, because the styles of js-dos changed the styles of the site. A test in Chrome showed that the page loads files from this site only.
• The lens on the game page: a new script (site/scripts/sync-game.mjs) lists the dictionary words that each program uses, and the new words that the dictionary does not have yet. Two reference lists make this possible: all 118 spellings of the original 8086 instructions, and all Fortran 2018 keywords (MIT license).
• A lesson from the first picture: the curve went down first. Screen rows count down from the top, so the routine now subtracts the sine from the center row.

Round 15: the A-side cassette photo, and work through pull requests

• What the owner asked: “commit. push. open PRs and merge to main”. All work was already on main, with no other branch. Thus, there was nothing to merge at that time. The owner then gave a photo of a cassette tape with the label “A Side. Assembly, the first language of the machine.” The request: use the photo for each part of the site that talks about the A side.
• The photo: learn/images/a-side-cassette.jpg (1448 x 1086 pixels, 186 KB, JPEG). The original file had no hidden metadata, for example no location. Astro makes smaller WebP copies for each page.
• Where it shows: the home page (the A-side card), the Start-here page, the A-side overview, the seven A-side segment pages, the compare page and the link-preview image. The B side has no photo yet. The code accepts a B-side photo in the same way (learn/images/ and site/src/lib/learn.ts).
• Pull requests: GitHub Actions now also runs the build and the game check for each pull request. Only a push to main publishes the site. This change went through a branch (a-side-cassette) and pull request #1, which merged after its checks passed.
• The B-side photo: the owner then gave a second photo, with the label “B Side. Fortran, the language that speaks maths.” It is learn/images/b-side-cassette.jpg (155 KB, no hidden metadata). It shows on each part of the site that talks about the B side, in the same places as the A-side photo. The link-preview image now shows the two cassettes. This change went through the branch b-side-cassette and pull request #2.

Round 16: eight video guides, split and reviewed

• What the owner asked: review the new documents in review/, split them so that each part can have an adversarial review, and include the original YouTube video of the prompt for each main idea. During the work, the owner also gave a new A-side photo with the label “Assembly - the first language of the machine”. It replaced the first A-side photo.
• The documents: four reports and four interactive pages, one pair for each video. The YouTube oEmbed service confirmed the four videos: “Assembly Language in 100 Seconds” and “FORTRAN in 100 Seconds” (Fireship), and E04 and E01 of the “FASTEST Computer Language” series (Dave’s Garage). The file review/findings/videos.json records them. The eight files moved to review/segments/, next to the first four.
• The split: 71 new document parts (10, 13, 15 and 9 for the reports, 6 for each page). The splitter now finds the script of an HTML section by the element IDs and handlers that the section uses. The first two pages keep the old method, so their parts and findings did not change.
• The captions: yt-dlp got the English captions of the four videos. They stay on this computer, in a scratch folder, and are not in the repository.
• The reviews: four helper agents reviewed one pair each: 169 findings (26 critical, 67 major, 76 minor), with the new evidence tag [VIDEO] on 50 findings. They also wrote the moment of each part in the video (review/findings/video-moments/). 60 of the 71 parts have a moment. The other parts say that the video does not cover the idea. The summary is adversarial-review-pass1/00-SUMMARY-video-guides.md.
• Largest results: the documents give the videos as the source of claims that the videos do not make. The E04 documents say COBOL is 40 to 50 times slower, but the video shows Fortran 1163 and COBOL 1118 passes (13:51). The E01 report reverses the Ada against Pascal result. The interactive “simulators” only swap text.
• New tool: review/findings/extract_findings.py reads the findings tables of any review batch and keeps the recorded statuses.

Round 17: A and B side by side on the game page

• What the owner asked: on the game page, show A and B side by side next to the dot. At each moment, show what the machine reads and calculates (A) and what maths it follows (B). The panels must change at the speed of the dot.
• The program: spike.asm now has keys. 1 to 5 set the speed (one step after 1, 2, 4, 8 or 16 screen refreshes, with the 8086 word XLAT for the table lookup). Space pauses, N moves one step, Esc stops. The default speed is about 9 steps each second. SPIKE.COM is 760 bytes, and the check still agrees on 256 of 256 values.
• The page: three columns: the A panel, the program, the B panel, with the two cassette photos. The page reads the screen of the emulator, finds the yellow dot and shows the work for its angle. Buttons press the program keys.
• Checks in Chrome: the real dot and the panel agreed on four samples in a row (for example, angle 53 at x = 85, y = 23). Pause kept the dot still, and one step moved it one angle. The page formula also agrees with the A-side test file on all 256 angles.
• A problem that the test found: the browser played an older copy of the program, with the curve upside down, from its own storage. The page now adds a fingerprint of the game files to their addresses (?v=...), so each new build loads fresh.
• Speed check: the automated browser tab was hidden, and the browser slows a hidden tab. Thus, the owner checked the speeds on the live page and confirmed that they work.

Round 18: the second test, the dot in 3D

• What the owner asked: the first test moves the dot on a flat plane. For the second test and a second page, give the plane depth, with the same movement of the dot.
• The world: X (left and right), Y (up and down, the sine) and Z (the depth). The first form used the cosine for the depth, so the dot went from the back to the front and back again. The owner then asked for a curve that starts at the back and ends at the front, with its middle point at the center of the 3D space. Now Z = 128 - angle and X = 1.5 * (angle - 128). At angle 128, the point is X = 0, Y = 0, Z = 0.
• The program: src/dot3d.asm draws a blue floor, the path in the air and its footprint on the floor. The dot has a pole down to its red shadow, and a near dot is larger. The routine project divides by the distance from the eye with the 8086 word IDIV. An undo list puts back the old pixels. DOT3D.COM is 1103 bytes.
• The check: test/check3d.asm writes the screen positions of 256 angles. lab/check_3d.f90 agrees on 256 of 256 points. The largest difference from exact maths is 1 pixel. A deliberate change of one number made the check fail.
• The page: /game/test2a/ (first at /game/3d/), with the A and B panels. The B panel draws the world from above and from the side, with the line from the eye to the dot. In Chrome, the panel followed the real dot (for example, angle 52 at x = 98, y = 74).

Round 19: one page for each test, and a wrong program

• What the owner asked: the page /game/ must show the tests. Test 1 goes to /game/test1/, and the 3D test goes to /game/test2a/. A new page /game/test2b/ must show what wrong values look like, and why the checks are necessary.
• The wrong program: the same files as test 2a, with one wrong word in path_point: shr dx, 1, not sar dx, 1. SHR puts a 0 in the sign bit, so each negative number becomes a large positive number. The switch -dWRONG_SIGN of NASM selects it. The program is safe to run: each wrong pixel is still in the screen memory.
• The result: the front half of the path is correct. The back half (angles 0 to 127) is dots all over the screen. The checker finds 128 of 256 points wrong and lists each wrong angle. build.sh requires this check to fail, so the build also tests the check.
• The pages: /game/ lists the three tests with the result of each check. The page of test 2b runs the wrong program, and shows the wrong word, the bits of SAR and SHR for the dot now, the correct and the wrong position, and a strip of the 256 angles in red and green. In Chrome, the page followed the dot also at wrong positions (for example, angle 41 at screen x = 12360).

Round 20: test 3, the wave turns

• What the owner asked: in test 3, make the dot turn around the center. /game/test3a/ is the correct program, and /game/test3b/ shows how a wrong maths value breaks the game. The sine wave goes from the back to the front.
• The maths: each point has its place on the wave, d = 128 - angle. After a turn T: X = d * sin(T), Z = d * cos(T). The cosine is the sine a quarter turn (64 steps) later. The wave turns one step for each two steps of the dot.
• Double buffering: the first form drew on the screen and flickered. In Chrome, the dot was missing in 3 of 5 screen samples. The program now draws each picture in a work buffer and copies it to the screen. After this change, the dot was on the screen in each sample.
• The wrong value: QUARTER_TURN equ 90 (degrees), not 64 (steps). The ring on the floor is a tilted oval, and the wave grows and shrinks. The check finds 3759 of 4096 points wrong. build.sh requires this check to fail.
• Shared code: the keys, the pixel address and the screen refresh are now in src/common.inc. DOT3D.COM has the same size as before (1103 bytes), and its check still passes.

Where things stand at the end of the session

• Live: https://kairin.github.io/000-111-learn/. GitHub Actions builds it from site/ (Astro + Starlight), which reads review/.
• Decided: learn both languages through a constrained game that a person can play in the browser (D11). Astro + Starlight (D12). The site first (D13). “Edit on GitHub” status tracking (D14).
• Open: O7, the game architecture (recommendation: C, split roles), and O8, the game concept and constraints. Next step: the Phase 4 toolchain spike after the owner selects O7.
• Round 13 result: the language lens (A side and B side) is the center of the site. All documents obey ASD-STE100.