Museum workshop edit regions, a settings menu, and five more languages by jamesmontemagno · Pull Request #14 · github/copilot-sdk-workshop

jamesmontemagno · 2026-10-02T16:05:50Z

This PR has grown to three parts. Each part is in its own commits, so it can be reviewed commit by commit.

Museum workshop: named edit regions and more pre-built helpers.
Site header: settings move behind a gear, and resource links move to a footer.
Languages: Japanese, Brazilian Portuguese, Spanish, French, and German, plus a Korean update for part 1.

Most of the 336 changed files are part 3: 47 translated Markdown files and one state file for each of the five new locales.

1. Museum workshop

Why

Working through the Museum Exhibit Studio track, it was hard to tell where each lesson's code belongs. Steps 1-3 said "replace the entire file", and later steps placed fragments with prose such as "beside the ones you already have". Learners also typed a lot of code that teaches nothing about the SDK, and following the lessons exactly did not produce the finished app.

What changed

Named edit regions (all six programming languages)

Every place a learner writes code is a named region in the starter entrypoint. The BEGIN line lists the steps that touch it:

// >>> BEGIN generation-config | Step 4: INSERT | Step 6: REPLACE
// <<< END generation-config

Each lesson code block is introduced by a line such as: REPLACE region generation-config in Program.cs:
INSERT fills an empty region. REPLACE means delete what is between the two markers, then paste. A block is always the whole region, so nothing is merged by hand.
The starter ships the fixed program shape (entry function, error handler, cleanup), so no lesson replaces the whole file. The markers stay in the finished app.
The preflight has a "How edits work" section and start-museum/README.md lists the 14 regions.

More code in the pre-built helpers

Plumbing: fact-set selection, the failure message, the COPILOT_MODEL lookup, source formatting.
Fixed prompt text: exhibit structure, page requirements, the research prompt.
System messages: a dedicated helper file per language holds the Step 3 curator message, the Step 6 curator message, and the research assistant message. Lessons install a message in replace mode instead of pasting it.
Learners still write all SDK code: tool registration, the three session configs, the session runner, and the instructions in the exhibit and page prompts.

Non-blank lines a learner writes in the entrypoint:

Language	Before	After
.NET	270	151
Node.js	232	156
Python	221	144
Go	265	165
Rust	297	184
Java	283	146

Step 3 lesson

Shows the curator system message and says what each paragraph does.
The off-topic prompt experiment is its own "Change the prompt" section and asks "Tell me about how git worktrees work."
The prompt asks for five sentences instead of two, so there is enough text to hear the voice.
The message no longer mentions the fact tool, which is not registered until Step 4. Step 4's prompt introduces it.

Validation (scripts/validate_workshop.py)

Applies every lesson block to the starter and requires the result to equal the finished entrypoint.
Rejects a lesson code block with no INSERT or REPLACE line, and one that pastes a system message.
Requires system message text quoted in a lesson to match every language's helper file.
The new system message files count as helpers, so starter and finished copies must be identical.

2. Site header

The header on the hub and in the lesson viewer was crowded. It now holds the brand, the Prev and Next step links (lessons only), and a gear.

Settings menu (gear): site language, programming language, and theme (Light or Dark). On the hub, the programming language in the menu and the picker on the page stay in sync.
Removed: the Hub link. The brand already links to the hub and keeps the selected language and workshop.
Moved to a footer: the SDK docs link, and the target app link on the hub.
Emoji and glyph icons in the header and step list are replaced with SVG.
The lesson header has a fixed height. Before, on narrow screens the progress bar sat a few pixels under the header and the page scrolled sideways.
The menu closes on Escape, on a click outside it, and when focus tabs out of it. Changing a setting leaves it open.

New files: docs/site-chrome.css and docs/settings-menu.js. docs/theme-toggle.js now drives two radio buttons instead of a toggle button.

3. Languages

New locales: ja-jp, pt-br, es-es, fr-fr, de-de. Each has the README, all lessons, the starter and finished-app notes, and the site interface strings.
New rule files for the localization skill: rules/fr-fr.md and rules/de-de.md, modeled on the existing ones. The other three locales already had rules.
Korean: updated for the part 1 lesson changes, and its README lists the new languages.
The root README lists all seven languages.
The per-language runtime notes on the hub ("Requires Python and…") moved from language-registry.js into locale-registry.js so they can be translated.
Japanese gets its own font stacks (docs/japanese-typography.css), using platform fonts rather than a download.

How the translations were kept faithful:

Code blocks, language directives, and HTML are copied from the English source, not retyped. A check renders every English file and its translation for all six programming languages with the site's Markdown renderer and compares the structure (headings, lists, tables, code, links, emphasis). The five new locales match exactly.
Lesson titles and recurring headings come from one fixed table per locale, so page titles, the step list, and cross-references agree.
INSERT, REPLACE, BEGIN, END, product names, and text that a model receives stay in English.
Links between translated files stay inside the locale. Links to files that are not translated point at the originals.
Each locale's .localization-state.json records the source fingerprint and commit for every file, as the skill requires, so the sync workflow sees them as current.

The site tests no longer name Korean. They check every registered locale for a complete set of interface strings with the right placeholders, a translated copy of every lesson, and a working lesson and demo guide through the viewer.

Things to know when reviewing

The new translations are machine-translated and not reviewed by native speakers. I checked terminology consistency across files and read samples in each language, but a native review of each locale is still needed. The same applies to the Korean text added here, which the Korean maintainer should review.
Not run against Copilot. I built the entrypoint as it stands after each of Steps 1-7 in all six programming languages, plus every starter and finished project, but sent no prompts. The Step 3 "git worktrees" refusal in particular is described, not observed.
Per-step builds are not in CI. They were a local one-off. CI checks that the lessons assemble to the finished entrypoint and that starter and finished build.
Browser checks were local. I drove the settings menu and loaded lessons in every locale in Edge (desktop and phone widths, both themes). Those scripts are not in the repository; the committed site tests run without a browser.
Wording learners will see changed. The research and page prompts now use the same wording in every programming language, and a failed run prints Could not generate the exhibit: <reason> everywhere.
Imports are re-pasted. The imports region is a REPLACE in most steps (every step in Node.js, Python, and Rust), because a block is always the full region and Go and Rust reject or warn on unused imports.
Go blocks end with a blank line. Top-level Go code blocks carry a trailing blank line because gofmt requires one before the END marker.
Session configs stay in the entrypoint. They are what Steps 4, 6, and 7 teach, so they were not moved to helpers.
Workshop names stay in English in every locale (SDK 101, Accessibility Reviewer, Museum Exhibit Studio).
Lesson times are unchanged, although learners now type less.

…lpers Every place a learner writes code in the Museum Exhibit Studio entrypoints is now a named region delimited by '>>> BEGIN' / '<<< END' marker comments whose BEGIN line lists the steps that touch it. Each lesson code block is introduced by an INSERT or REPLACE line naming its region and holds the region's complete contents, so no lesson replaces the whole file or places code by prose. The starters ship the fixed program shape (entry function, error handler, cleanup). Plumbing and fixed prompt text move into the pre-built helpers in all six languages: fact selection, the failure message, the COPILOT_MODEL lookup, source formatting, the exhibit structure, the page requirements, and the research prompt. Learners still write all SDK code. Content validation now applies every lesson block to the starter and requires the result to equal the finished entrypoint, and rejects any lesson code block without an edit line. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

The curator and research system messages were the largest things learners pasted into the entrypoint. Each language now ships them in a dedicated pre-built file (three constants: the Step 3 curator message, the Step 6 curator message that ranks approved facts over research, and the research assistant message). Lessons wire a message into the session config in replace mode instead of pasting it, and Step 6 switches the generation config to the research-aware message. The two system message regions leave the entrypoints, so each has 14 regions. Content validation treats the new files as helpers (identical in starter and finished), and rejects a lesson code block that pastes a system message. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

…s own section Step 3 quotes the pre-built curator system message and says what each paragraph does, so learners read it in the lesson before wiring it in. The off-topic prompt experiment moves out of Run it into a Change the prompt section and now asks about git worktrees, a question the default coding persona would answer. Content validation checks that the system message text quoted in Steps 3 and 6 matches every language's helper file. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

With the curator system message installed, two sentences is too little text to hear the change in voice. Step 3 now asks for five, says so where the generate region changes, and its sample output and the prompt-reset instruction match. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot

Copilot review overview

🟡 Changes recommended

Step 3 requires an unavailable fact tool, and Java can emit duplicate failure diagnostics during cleanup.

Review effort: Balanced
Findings: 6 · 2

Open (8)

Tool registration occurs after the message requiring the tool · New
Tool registration occurs after the message requiring the tool · New
Tool registration occurs after the message requiring the tool · New
Tool registration occurs after the message requiring the tool · New
Tool registration occurs after the message requiring the tool · New
Tool registration occurs after the message requiring the tool · New
Close failure causes duplicate error reporting · New
Close failure causes duplicate error reporting · New

What changed in this PR

This PR restructures the Museum Exhibit Studio workshop so learners edit named regions while shared plumbing and prompts remain in synchronized helpers.

Changes:

Adds INSERT/REPLACE regions and validates lesson assembly against finished entrypoints.
Moves fixed prompts, system messages, failure handling, and selection utilities into helpers.
Updates all six language starters, lessons, and finished samples.

File	Description
`README.md`	Documents named regions and validation.
`scripts/validate_workshop.py`	Validates regions, lesson assembly, and helper parity.
`workshop/museum-00-preflight.md`	Explains region-based editing.
`workshop/museum-01-first-curator-session.md`	Converts initial setup to region edits.
`workshop/museum-02-stream-the-curator.md`	Converts streaming setup to region edits.
`workshop/museum-03-curator-voice.md`	Wires pre-built system messages.
`workshop/museum-04-approved-facts.md`	Updates fact-grounding regions.
`workshop/museum-06-prove-the-structure.md`	Separates generation and validation regions.
`workshop/museum-07-wikipedia-research.md`	Updates research regions and helpers.
`workshop/museum-08-interactive-exhibit-page.md`	Updates HTML-generation regions.
`start-museum/README.md`	Documents starter layout and regions.
`start-museum/dotnet/Program.cs`	Adds fixed scaffolding and regions.
`start-museum/dotnet/Helpers/CuratorPrompts.cs`	Adds fixed prompt text.
`start-museum/dotnet/Helpers/CuratorSafety.cs`	Adds source formatting.
`start-museum/dotnet/Helpers/CuratorStreamer.cs`	Adds model selection.
`start-museum/dotnet/Helpers/CuratorSystemMessages.cs`	Adds pre-built system messages.
`start-museum/dotnet/Helpers/CuratorTerminal.cs`	Adds fact selection and failure formatting.
`start-museum/nodejs/src/index.ts`	Adds fixed scaffolding and regions.
`start-museum/nodejs/src/curator.ts`	Expands shared helper behavior.
`start-museum/nodejs/src/system-messages.ts`	Adds pre-built system messages.
`start-museum/python/main.py`	Adds fixed scaffolding and regions.
`start-museum/python/curator.py`	Expands shared helper behavior.
`start-museum/python/system_messages.py`	Adds pre-built system messages.
`start-museum/go/main.go`	Adds fixed scaffolding and regions.
`start-museum/go/curator.go`	Expands shared helper behavior.
`start-museum/go/system_messages.go`	Adds pre-built system messages.
`start-museum/rust/src/main.rs`	Adds fixed scaffolding and regions.
`start-museum/rust/src/lib.rs`	Expands and re-exports helpers.
`start-museum/rust/src/system_messages.rs`	Adds pre-built system messages.
`start-museum/java/src/main/java/workshop/MuseumExhibitStudio.java`	Adds fixed scaffolding and regions.
`start-museum/java/src/main/java/workshop/CuratorPrompts.java`	Adds fixed prompt text.
`start-museum/java/src/main/java/workshop/CuratorSafety.java`	Adds source formatting.
`start-museum/java/src/main/java/workshop/CuratorStreamer.java`	Adds model selection.
`start-museum/java/src/main/java/workshop/CuratorSystemMessages.java`	Adds pre-built system messages.
`start-museum/java/src/main/java/workshop/CuratorTerminal.java`	Adds fact selection and failure formatting.
`finished/dotnet/museum-exhibit-studio/README.md`	Documents finished sample structure.
`finished/dotnet/museum-exhibit-studio/Program.cs`	Aligns the finished entrypoint with lessons.
`finished/dotnet/museum-exhibit-studio/Helpers/CuratorPrompts.cs`	Mirrors fixed prompt helpers.
`finished/dotnet/museum-exhibit-studio/Helpers/CuratorSafety.cs`	Mirrors source formatting.
`finished/dotnet/museum-exhibit-studio/Helpers/CuratorStreamer.cs`	Mirrors model selection.
`finished/dotnet/museum-exhibit-studio/Helpers/CuratorSystemMessages.cs`	Mirrors system messages.
`finished/dotnet/museum-exhibit-studio/Helpers/CuratorTerminal.cs`	Mirrors terminal helpers.
`finished/nodejs/museum-exhibit-studio/README.md`	Documents finished sample structure.
`finished/nodejs/museum-exhibit-studio/src/index.ts`	Aligns the finished entrypoint with lessons.
`finished/nodejs/museum-exhibit-studio/src/curator.ts`	Mirrors shared helpers.
`finished/nodejs/museum-exhibit-studio/src/system-messages.ts`	Mirrors system messages.
`finished/python/museum-exhibit-studio/README.md`	Documents finished sample structure.
`finished/python/museum-exhibit-studio/main.py`	Aligns the finished entrypoint with lessons.
`finished/python/museum-exhibit-studio/curator.py`	Mirrors shared helpers.
`finished/python/museum-exhibit-studio/system_messages.py`	Mirrors system messages.
`finished/go/museum-exhibit-studio/README.md`	Documents finished sample structure.
`finished/go/museum-exhibit-studio/main.go`	Aligns the finished entrypoint with lessons.
`finished/go/museum-exhibit-studio/curator.go`	Mirrors shared helpers.
`finished/go/museum-exhibit-studio/system_messages.go`	Mirrors system messages.
`finished/rust/museum-exhibit-studio/README.md`	Documents finished sample structure.
`finished/rust/museum-exhibit-studio/src/main.rs`	Aligns the finished entrypoint with lessons.
`finished/rust/museum-exhibit-studio/src/lib.rs`	Mirrors and re-exports helpers.
`finished/rust/museum-exhibit-studio/src/system_messages.rs`	Mirrors system messages.
`finished/java/museum-exhibit-studio/README.md`	Documents finished sample structure.
`finished/java/museum-exhibit-studio/src/main/java/workshop/MuseumExhibitStudio.java`	Aligns the finished entrypoint with lessons.
`finished/java/museum-exhibit-studio/src/main/java/workshop/CuratorPrompts.java`	Mirrors fixed prompt helpers.
`finished/java/museum-exhibit-studio/src/main/java/workshop/CuratorSafety.java`	Mirrors source formatting.
`finished/java/museum-exhibit-studio/src/main/java/workshop/CuratorStreamer.java`	Mirrors model selection.
`finished/java/museum-exhibit-studio/src/main/java/workshop/CuratorSystemMessages.java`	Mirrors system messages.
`finished/java/museum-exhibit-studio/src/main/java/workshop/CuratorTerminal.java`	Mirrors terminal helpers.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

…se handling The Step 3 system message told the curator to call an approved fact tool and not to use its own knowledge, but no tool is registered until Step 4, so a model that followed it could not write the requested text. The message now covers role, voice, scope, and output only. Step 4's exhibit prompt is where the curator is first told where its facts come from, and Step 6's message adds the source rule as standing policy. Lessons 3, 4, and 6 say so. The Java entrypoint printed a second, misleading failure message if closing the terminal threw after a failed run. It ignores a close failure again, as it did before the region conversion. Both changes address review comments on the pull request. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Brings in the Korean (ko-kr) localization, the locale switcher, the localization sync workflow, and the intro Java Maven wrapper. No conflicts. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

The Korean (ko-kr) translations of the eight museum lessons, the root README, start-museum/README.md, and the six finished museum READMEs predate this branch's English changes (named edit regions, pre-built helpers and system messages, the Step 3 rewrite). Following .github/skills/localizations/SKILL.md: each file's recorded source baseline was verified, the existing Korean was kept for every block whose English is unchanged, code blocks were taken verbatim from the English sources, and only the new or changed prose blocks (208 unique) were translated, matching each file's existing terminology. The lines that introduce code blocks keep the INSERT and REPLACE keywords in English because they match the marker comments in the starter files. .localization-state.json records the new source and localized fingerprints for the 16 files. The new Korean text is machine-translated and has not been reviewed by a Korean speaker. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

The header on the hub and the lesson viewer now holds only the brand, the step links, and a settings menu. The menu owns the documentation language, the programming language, and the theme. The Hub link is gone because the brand already links home, and the SDK docs and target app links move to a footer. Emoji and glyph icons in the touched chrome are replaced with SVG, and the lesson header has a fixed height so the progress bar no longer slides under it. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Add French and German rules for the localization skill, list the new languages in the README, give Japanese its own font stacks, and move the per-language runtime notes into the locale registry so they can be translated. The site tests now check every registered locale for complete interface strings and content instead of naming Korean. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Translate the README, the lessons, the starter and finished-app notes, and the site interface into Japanese (ja-jp). Code blocks, commands, and link targets are identical to the English sources, and each file's source baseline is recorded in .localization-state.json. The text is machine-translated and has not been reviewed by a native speaker. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Translate the README, the lessons, the starter and finished-app notes, and the site interface into Brazilian Portuguese (pt-br). Code blocks, commands, and link targets are identical to the English sources, and each file's source baseline is recorded in .localization-state.json. The text is machine-translated and has not been reviewed by a native speaker. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Translate the README, the lessons, the starter and finished-app notes, and the site interface into Spanish (es-es). Code blocks, commands, and link targets are identical to the English sources, and each file's source baseline is recorded in .localization-state.json. The text is machine-translated and has not been reviewed by a native speaker. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Translate the README, the lessons, the starter and finished-app notes, and the site interface into French (fr-fr). Code blocks, commands, and link targets are identical to the English sources, and each file's source baseline is recorded in .localization-state.json. The text is machine-translated and has not been reviewed by a native speaker. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Translate the README, the lessons, the starter and finished-app notes, and the site interface into German (de-de). Code blocks, commands, and link targets are identical to the English sources, and each file's source baseline is recorded in .localization-state.json. The text is machine-translated and has not been reviewed by a native speaker. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

jamesmontemagno and others added 4 commits October 1, 2026 20:07

Copilot AI balanced review requested due to automatic review settings October 2, 2026 16:05

Copilot started reviewing on behalf of jamesmontemagno October 2, 2026 16:06 View session

Copilot AI reviewed Oct 2, 2026

View reviewed changes

jamesmontemagno and others added 12 commits October 2, 2026 09:18

Merge branch 'main' into motz-museum-workshop-insertion-markers

1681da5

Brings in the Korean (ko-kr) localization, the locale switcher, the localization sync workflow, and the intro Java Maven wrapper. No conflicts. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

List the new languages in the Korean README

76ece49

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Test every locale's lessons through the lesson viewer

ec9f4b4

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

jamesmontemagno changed the title ~~Museum workshop: named edit regions and more pre-built helpers~~ Museum workshop edit regions, a settings menu, and five more languages Oct 5, 2026

jamesmontemagno merged commit c086d49 into main Oct 5, 2026
17 checks passed

Navigation Menu

Repository navigation

Museum workshop edit regions, a settings menu, and five more languages - #14

Museum workshop edit regions, a settings menu, and five more languages#14
jamesmontemagno merged 16 commits into
mainfrom
motz-museum-workshop-insertion-markers

jamesmontemagno commented Oct 2, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jamesmontemagno commented Oct 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

1. Museum workshop

Why

What changed

2. Site header

3. Languages

Things to know when reviewing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jamesmontemagno commented Oct 2, 2026 •

edited

Loading