@@ -7,6 +7,8 @@ Read `AGENTS.md`, `docs/reference/io_contract.md`, `docs/reference/figure-specif
 
 Check that the repair keeps the four category labels and group assignments unchanged: Group A counts are 42, 31, 18, 9; Group B counts are 64, 18, 12, 6. Preserve category order and show Group A above Group B within each category. Trace plotting options, function calls, and output handling. Do not open data tables, participant records, or study logs, and do not explain why an individual value failed.
 
+Review whether the change is proportionate to this figure repair and understandable to a Python or R researcher. Check new dependencies, configuration, classes, helpers, duplicated logic, and extra processing against actual requirements. Flag concrete unnecessary complexity with its source location, maintenance or execution cost, and a simpler alternative that preserves behavior, validation, and accessibility. Do not infer a defect from line count alone or recommend terse code at the expense of clarity. Passing checks does not establish maintainability or efficiency; require measurements or a specific account of the operations involved for performance claims, and distinguish estimates from measurements.
+
 When tools permit, run `python -m unittest discover -s plotting/tests` or `Rscript plotting/tests/run_tests.R` and use the pass/fail evidence. Run the selected language's `plotting/check_figure.py` or `plotting/check_figure.R` with `--output` and an ignored PNG path when execution is permitted. The starter intentionally fails this stricter acceptance check. Inspect the rendered chart against every fictional journal requirement, including grouping, legend, and full readable labels. Record image inspection as untested when image tools are unavailable. A passing test suite alone does not establish visual quality.
 
 Review accessibility explicitly: black text on white, visible bar outlines, readable labels at the intended size, and group identification that survives grayscale. Read `runs/with-fix/summary.alt.txt` and compare its group names, values, and summary with the invented constants and chart. Check that the description will be attached when the image is used; a sidecar file alone does not provide screen-reader access. Record visual or assistive-technology checks that were unavailable.
 
@@ -6,6 +6,8 @@ Read AGENTS.md and use .agents/skills/plot-review/SKILL.md in the target reposit
 Review source code, tests, and the chart made from invented summary counts.
 Do not inspect data tables, participant records, or study logs.
 Report code findings and visual observations separately, with actual check results.
-Do not edit files. If permissions prevent execution or image inspection, report
+Do not edit the reviewed checkout, including generated outputs or Git state.
+Use supplied evidence or permitted scratch copies for checks that write files.
+If permissions prevent execution or image inspection, report
 which supplied evidence you reviewed and which checks remain unrun.
 """
@@ -8,6 +8,12 @@ Read `README.md`, `REPO_MAP.md`, and the relevant page in `docs/paths/python/` o
 
 The starting chart deliberately overlaps two groups and clips long labels. Preserve that unfinished exercise during maintenance unless the user asks to solve it. For a learner's repair, change the plotting function to make the grouped chart follow `docs/reference/figure-specifications.md` while preserving categories, counts, group assignments, and order.
 
+## Keep the repair proportionate
+
+Make the smallest clear change that meets the figure requirements and that a Python or R researcher can explain and maintain. Work in the existing plotting function. Prefer direct code and the current dependencies; justify any new dependency, configuration, class, helper, or extra processing by a concrete need in this task. Do not turn a figure repair into an unrequested production pipeline or reusable framework. If the task appears to require broader work, explain the scope increase and a simpler alternative and wait for the learner's decision before expanding the scope.
+
+Simplicity includes readable names and useful comments, validation, and accessibility. Do not remove these to reduce line count or compress code into clever expressions. Avoid repeated work and unnecessary computation; do not optimize hypothetical future workloads. Passing tests does not establish maintainability or efficiency. Support performance claims with measurements or a specific explanation of the operations involved, and label estimates as estimates.
+
 ## Explore code and the chart
 
 Explain source files, function calls, and tests. Do not open individual-level data, inspect participant records, or diagnose why a data point failed. This exercise has no participant records or data-file inputs. Its fixed aggregate counts are invented and embedded in source code.
@@ -16,6 +22,12 @@ Use the supplied chart to discuss labels, spacing, axes, and readability. Run th
 
 When reusing this workflow, work in a separate workspace with code permitted for the selected service and invented examples. Keep study data, exports, logs, credentials, and sensitive code literals outside the agent's access. A local terminal, read-only mode, or `.gitignore` is not a data-sharing permission. See `docs/reference/lab-data-policy.md`.
 
+## Keep the learner in control
+
+Follow the chosen client and the learner's current stage. The default walkthrough uses VS Code with Copilot's Local Ask → Plan → Agent roles, Explorer, and Source Control; complete terminal instructions are in `docs/appendix/command-line.md`. Explanation, planning, and verification-only requests do not authorize repairs.
+
+Use `docs/reference/agent-control.md` for permission and independence guidance. Explain the purpose, affected files or network access, and duration of a permission request without encouraging automatic approval. Honor existing authorization; do not broaden access, disable safeguards, or change global settings to bypass a failure. Instructions and skills do not enforce a sandbox. Leave the learner able to explain and maintain the code: provide checkable reasoning, actual evidence, and the requested opportunity to review before proceeding.
+
 ## Verify and hand off
 
 From the repository root, run the chosen language's checks:
@@ -28,6 +40,8 @@ python -m unittest discover -s plotting/tests
 Rscript plotting/tests/run_tests.R
 ```
 
+Also run the selected language's separate figure checker as described in `docs/appendix/command-line.md`. Its rejection of the unfinished starter is intentional; a completed repair must pass both behavior and figure checks against the latest source. Verification-only requests must report failures without making further repairs.
+
 Render a new image, compare it with the saved baseline, and inspect the code diff. Follow the journal's accessibility requirements: review contrast, legibility, and group identification without color, and write accurate alternative text in `runs/with-fix/summary.alt.txt`. Attach that text when placing the image in a document or slide. Consider accessibility whenever creating an artifact for others to use. Keep `runs/` and `tmp/` ignored. Use `.agents/skills/plot-review/SKILL.md` for a requested independent review. The optional `lab-r-refactor` skill applies the local R template without changing behavior.
 
 Preserve unrelated work and agree on file ownership with other agents. Finish with what changed, actual commands and outcomes, visual observations, and anything untested. Do not publish or modify external services without authorization.
@@ -1,17 +1,25 @@
 # Practical GenAI Agentic Coding Example
 
-**Fix a plotting function and see the improvement.** Start with a chart whose groups overlap and long labels are clipped. Use a short request, a local journal brief, and checks you can inspect.
+**Fix a plotting function and see the improvement.** Start with a chart whose groups overlap and long labels are clipped. Use VS Code + GitHub Copilot to discuss the repair in Chat, inspect charts in Explorer, and review color-coded code changes in Source Control.
 
 This is the runnable exercise for [Part 2 of the Fritsche Lab Practical GenAI series](https://fritschelab.org/practical-genai-agentic-coding-guide/), by [Lars G. Fritsche](https://medschool.umich.edu/profile/4980/lars-fritsche) and the [Fritsche Lab](https://fritschelab.org/) at the University of Michigan. [Part 1](https://fritschelab.org/practical-genai-coding-guide/) introduces planning, context, and checking an assistant's work. Accessibility belongs in the brief and review: consider contrast, legibility, and alternative text whenever creating something others will use.
 
+**Practising what we teach:** this guide and exercise were developed with substantial AI assistance in writing, coding, testing, and review. They are provided **as is, without warranty**, to the extent permitted by applicable law. Review the code, agent instructions, permissions, and results before use. Read the [AI-assistance disclosure, use guidance, and warranty notice](docs/reference/agent-control.md#about-ai-assistance-in-this-guide).
+
 ## Choose your path
 
+Start with the [detailed VS Code + GitHub Copilot setup](docs/setup/vscode-copilot.md). It covers Windows, macOS, Git installation, Copilot access, cloning, and the **Ask / Plan / Agent** controls. VS Code includes Git controls and uses a separately installed Git program.
+
 | Path | Requirements | Follow online | Follow here |
 | --- | --- | --- | --- |
 | Python | Python 3.10–3.12, Git, and Matplotlib | [Python walkthrough](https://fritschelab.org/practical-genai-agentic-coding-guide/docs/paths/python/) | [Python setup and six lessons](docs/paths/python/index.md) |
 | R | R 4.1 or later and Git; no extra R packages | [R walkthrough](https://fritschelab.org/practical-genai-agentic-coding-guide/docs/paths/r/) | [R setup and six lessons](docs/paths/r/index.md) |
 
-Install only your chosen language. Its setup page gives the commands to create the starting chart. Both paths follow the same six stages: orient, specify, implement, verify, review, and hand off.
+Install only your chosen language. Have Copilot prepare it and run the starting code, then inspect the result yourself. Both paths follow six stages: **Ask** to orient, **Plan** the repair, **Agent** to implement and verify, then **Source Control** to review diffs, stage source files, and commit locally.
+
+Prefer a terminal? The [CLI appendix](docs/appendix/command-line.md) keeps complete Python and R setup, rendering, checking, and Git commands, plus optional Copilot CLI guidance.
+
+Read [permissions and independent work](docs/reference/agent-control.md) before approving agent actions. Keep repairs small enough to understand and practise without AI too: working output does not establish that you can maintain the code if access becomes unavailable or prohibited.
 
 ## What the agent works with
 
@@ -22,7 +30,7 @@ Install only your chosen language. Its setup page gives the commands to create t
 - [Plot repair brief](docs/lessons/02-specify.md): the visible problem and acceptance criteria.
 - [Plotting contract](docs/reference/io_contract.md): fixed counts, command interface, and output expectations.
 - [Journal specifications for figures](docs/reference/figure-specifications.md): the fictional journal's precise layout, styling, accessibility, and alternative-text requirements.
-- [Repository map](REPO_MAP.md): files, tests, and commands.
+- [Repository map](REPO_MAP.md): source files, tests, outputs, and instructions.
 - [AGENTS.md](AGENTS.md): focused instructions for your coding agent.
 - [Invented summary counts](docs/reference/synthetic-data.md): what the chart represents.
 - [Templates](docs/templates/index.md): optional briefs, contracts, and handoffs.
 
@@ -1,6 +1,6 @@
 # Repository map
 
-Start with `README.md`, then follow your chosen language through `docs/paths/python/` or `docs/paths/r/`.
+Start with [VS Code + GitHub Copilot setup](docs/setup/vscode-copilot.md), then follow [Python](docs/paths/python/index.md) or [R](docs/paths/r/index.md). Use Explorer for source files and charts, Copilot Chat for Ask/Plan/Agent, and Source Control for changed files, diffs, staging, and local commits.
 
 ## Plotting exercise
 
@@ -10,12 +10,15 @@ Start with `README.md`, then follow your chosen language through `docs/paths/pyt
 | `plotting/plot_summary.R` | The equivalent base-R plotting function and CLI. |
 | `plotting/tests/` | Independent behavioral checks for both languages. |
 | `requirements-plotting.txt` | Python plotting dependency. |
+| `docs/setup/vscode-copilot.md` | VS Code, Git, Copilot, language environments, and the baseline. |
+| `docs/appendix/command-line.md` | Complete optional Python/R terminal workflows and Copilot CLI guidance. |
 | `docs/lessons/02-specify.md` | Plot repair brief and visual acceptance criteria. |
 | `plotting/check_figure.py`, `plotting/check_figure.R` | Separate journal figure acceptance checks; the starter intentionally fails them. |
 | `docs/reference/figure-specifications.md` | Fictional journal rules for dimensions, fonts, colors, and grouped layout. |
 | `docs/reference/io_contract.md` | Categories, counts, commands, and output expectations. |
 | `docs/reference/synthetic-data.md` | Why the aggregate counts are safe teaching examples. |
 | `docs/reference/lab-data-policy.md` | Boundaries when taking the workflow to study code. |
+| `docs/reference/agent-control.md` | Approval fatigue, permissions, sandbox limits, and maintaining independent coding skills. |
 | `examples/r_refactor/` | Optional compact R starter, formatted reference, and behavior verifier. |
 
 ## Reusable instructions
@@ -29,14 +32,15 @@ Start with `README.md`, then follow your chosen language through `docs/paths/pyt
 - `.codex/config.toml`: shared Codex defaults; actual access depends on the session.
 - `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`: client pointers to the common instructions.
 
-## Checks from this repository root
+## Checks and generated files
 
-```bash
-python -m unittest discover -s plotting/tests
-```
+Use the [Python verification lesson](docs/paths/python/04-verify.md) or [R verification lesson](docs/paths/r/04-verify.md). Its Agent prompt runs behavior tests and the separate figure checker against the current workspace. The [CLI appendix](docs/appendix/command-line.md) supplies exact terminal commands.
 
-```bash
-Rscript plotting/tests/run_tests.R
-```
+| Path | Where to inspect it |
+| --- | --- |
+| `runs/baseline/summary.png` | Explorer: preserve the starting chart for comparison. |
+| `runs/with-fix/summary.png` | Explorer: inspect the repaired chart after the latest checks. |
+| `runs/with-fix/summary.alt.txt` | Explorer: read the separately authored description and check every value. |
+| Modified or new source files | Source Control: inspect each diff before staging and committing. |
 
-Use your language path to render baseline and repaired images. Passing checks confirms tested behavior; inspect the image separately for readable labels and layout. Keep `runs/`, `tmp/`, environments, and caches out of Git.
+The starter passes behavior tests and fails the figure checker. Inspect readability and accessibility yourself even after both pass. `runs/`, `tmp/`, environments, and caches are ignored by Git, so generated figures and alt text appear in Explorer but stay out of Source Control and source commits.