If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/microsoft/RustTraining shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 1w ago
• 28+ active contributors
• MIT licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 62% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live microsoft/RustTraining repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/microsoft/RustTraining.

What it runs against: a local clone of microsoft/RustTraining — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in microsoft/RustTraining | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 37 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of microsoft/RustTraining. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/microsoft/RustTraining.git
#   cd RustTraining
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of microsoft/RustTraining and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "microsoft/RustTraining(\\.git)?\\b" \\
  && ok "origin remote is microsoft/RustTraining" \\
  || miss "origin remote is not microsoft/RustTraining (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "async-book/src/SUMMARY.md" \\
  && ok "async-book/src/SUMMARY.md" \\
  || miss "missing critical file: async-book/src/SUMMARY.md"
test -f "c-cpp-book/src/SUMMARY.md" \\
  && ok "c-cpp-book/src/SUMMARY.md" \\
  || miss "missing critical file: c-cpp-book/src/SUMMARY.md"
test -f "csharp-book/src/SUMMARY.md" \\
  && ok "csharp-book/src/SUMMARY.md" \\
  || miss "missing critical file: csharp-book/src/SUMMARY.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 37 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~7d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/microsoft/RustTraining"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

microsoft/RustTraining is a comprehensive, multi-level Rust curriculum spanning seven training books (for C++/C developers, JavaScript developers, and language-agnostic learners) plus specialized deep-dives into async Rust, advanced patterns, and engineering practices. It combines original pedagogical content with curated knowledge from the Rust ecosystem to provide beginner-to-expert progression with hands-on exercises and capstone projects. Monorepo structure with three main book directories: async-book/, c-cpp-book/, and additional language-specific books (implied by 'seven training courses'). Each book follows mdBook format (book.toml, src/SUMMARY.md, ch##-*.md chapters). Root Cargo.toml defines workspace with xtask member for automation. GitHub Pages deployment configured via .github/workflows/pages.yml.

Junior and mid-level software engineers transitioning to Rust from C++, C, or JavaScript backgrounds; teams adopting Rust who need structured internal training materials; self-taught learners seeking a cohesive curriculum that bridges gaps between scattered blog posts and official documentation.

Actively maintained and mature. The repo contains well-structured mdBook-based training materials (async-book, c-cpp-book directories with 15+ chapters each), dual licensing (MIT + CC-BY-4.0), GitHub Actions CI/CD pipeline (pages.yml), and formal contribution guidelines (CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md). This is production-ready training content from Microsoft.

Very low risk. This is training/documentation material, not a runtime library, so no dependency vulnerabilities propagate downstream. Single-maintainer risk is mitigated by Microsoft ownership and open contribution model. The workspace uses Cargo with resolver 2, indicating modern tooling. No security or stability concerns for consuming the content.

Actively building out the async and C++/C transition curriculum. The async-book contains 17 chapters from fundamentals (Future trait, Pin) through advanced topics (streams, async traits, production patterns, capstone project in ch17-capstone-project.md). The c-cpp-book covers Rust ownership/borrowing with deep-dives (ch07-1, ch07-2) on lifetimes and smart pointers specific to C++ developers.

Clone the repository and build the books locally: git clone https://github.com/microsoft/RustTraining.git && cd RustTraining. Install mdBook: cargo install mdbook. Serve async-book locally: cd async-book && mdbook serve. Open http://localhost:3000 in your browser. For c-cpp-book: cd ../c-cpp-book && mdbook serve.

Daily commands: No traditional 'run' command; this is training documentation. To build HTML locally: install mdbook (cargo install mdbook), then mdbook build in any book directory (async-book/, c-cpp-book/, etc.). Serve with mdbook serve for live-reload authoring. CI automatically publishes to GitHub Pages on push.

• README.md — Entry point describing the seven training courses and dual-license structure; essential for understanding the repo's scope and learning paths.
• Cargo.toml — Workspace configuration defining all member crates and dependencies; required to build and navigate the monorepo structure.
• async-book/src/SUMMARY.md — Table of contents for the async deep-dive course, organizing 17 chapters on Futures, Pin, executors, and production patterns.
• c-cpp-book/src/SUMMARY.md — Curriculum for C/C++ developers transitioning to Rust, covering ownership, safety, and advanced patterns—largest audience track in the repo.
• csharp-book/src/SUMMARY.md — Curriculum for C# developers, mapping .NET concepts to Rust idioms and covering async/await, smart pointers, and error handling.
• .github/workflows/pages.yml — CI/CD pipeline that builds and deploys the mdBook documentation sites; critical for keeping published training material in sync.
• CONTRIBUTING.md — Contribution guidelines and expectations for adding new chapters, examples, or exercises across all training courses.

Add a new chapter to an existing training course

1. Edit the target course's SUMMARY.md to add chapter title and link (e.g., csharp-book/src/SUMMARY.md) (csharp-book/src/SUMMARY.md)
2. Create new markdown file following naming convention (e.g., ch20-new-topic.md) in the course's src/ directory (csharp-book/src/ch20-new-topic.md)
3. Write content using mdBook-compatible Markdown with code blocks, callouts, and links to other chapters (csharp-book/src/ch20-new-topic.md)
4. Run local mdBook build via GitHub Pages workflow or xtask to preview rendered output (.github/workflows/pages.yml)

Create a new language-specific training track

1. Create new directory (e.g., java-book/) and populate with book.toml, mermaid assets, and src/ folder structure (java-book/book.toml)
2. Create src/SUMMARY.md with course outline and cross-language equivalence mappings (java-book/src/SUMMARY.md)
3. Create ch00-introduction.md explaining motivation for target audience (Java developers) (java-book/src/ch00-introduction.md)
4. Update root README.md to reference new training track and link to published site (README.md)
5. Update .github/workflows/pages.yml to include new book in build matrix if deploying separate sites (.github/workflows/pages.yml)

Add hands-on exercises and code examples to a chapter

1. Add exercise section to target chapter markdown with problem statement and skeleton code blocks (async-book/src/ch15-exercises.md)
2. Create accompanying example files in src/ with complete solutions or partial stubs (async-book/src/ch15-exercises.md)
3. Use syntax highlighting with language annotations (rust, c++, ```csharp) in markdown (async-book/src/ch15-exercises.md)
4. Link exercises to capstone project or later chapters to reinforce learning outcomes (async-book/src/ch17-capstone-project.md)

• mdBook — Lightweight, Rust-native static site generator for multi-format documentation; easy to version control and deploy to GitHub Pages.
• Markdown + Mermaid — Enables non-programmers to write and update content; Mermaid diagrams render inline for architecture and sequence visualization without external tools.
• Cargo workspace — Monorepo structure unifies all training tracks under a single Rust build system; xtask enables cross-course utilities and shared examples.
• GitHub Actions + Pages — Zero-cost hosting and automated CI/CD for building and deploying all four mdBook sites on every commit to main branch.

• Static HTML sites instead of interactive REPL/runnable examples

  • Why: Keeps content lightweight, offline-accessible, and version-controlled; reduces server maintenance overhead.
  • Consequence: Learners must clone repo and use local Rust toolchain to run exercises; no immediate browser-based feedback.

• Language-specific tracks (C++, C#, async) instead of monolithic course

  • Why: Allows audience segmentation and prerequisite mapping tailored to career backgrounds; reduces cognitive load.
  • Consequence: Content duplication of core Rust concepts across tracks; requires coordination when updating fundamental chapters.

• Dual licensing (MIT + CC-BY-4.0) for code and docs

  • Why: Permits both commercial reuse and academic attribution; aligns with Microsoft open-source policy.
  • Consequence: Contributors must acknowledge dual license and respect both code and documentation IP constraints.

• No interactive exercises in browser (requires local setup)

  • Why: Avoids dependency on cloud infrastructure, compilation services, or real-time execution environment.
  • Consequence: Higher barrier to entry for absolute beginners; assumes learners have Rust toolchain installed.

• Real-time collaborative IDE or REPL—this is static, versioned training material.
• Automatic code validation or CI checks for submitted exercises—content is self-grading.
• Coverage of Rust standard library API exhaustively—focuses on language semantics and idioms.
• Integration with external learning platforms or LMS—

1. mdBook version expectations: Mermaid diagram support requires mdBook 0.4.0+; ensure cargo install mdbook pulls recent version. 2. No local Rust examples tested: The .md files contain code snippets but no automatic compilation/test via cargo test—readers must manually verify code in separate Rust projects. 3. Workspace member xtask: Defined in Cargo.toml but not visible in file list; check xtask/ directory for build automation tasks if publishing locally. 4. Dual licensing: CC-BY-4.0 for docs means derivative works must attribute; CONTRIBUTING.md likely specifies contributor license agreement (CLA) for Microsoft projects.

• Pin and Unpin — Learners studying async-book/src/ch04-pin-and-unpin.md must understand Rust's guarantee that self-referential Future structs (created by async/await) don't move in memory—foundational for safe async design.
• State Machine Transformation (async/await desugaring) — Covered in async-book/src/ch05-the-state-machine-reveal.md; understanding how the compiler turns async functions into explicit state machines demystifies performance and debugging.
• Borrow Checker and Lifetime Elision — Core to c-cpp-book/src/ch07-1-lifetimes-and-borrowing-deep-dive.md; C++ developers must internalize Rust's compile-time memory safety model vs. runtime undefined behavior.
• Interior Mutability (Cell, RefCell, Mutex, Arc) — Detailed in c-cpp-book/src/ch07-2-smart-pointers-and-interior-mutability.md; essential pattern for shared mutable state without explicit locks, bridging C++'s mutable members to Rust's strict ownership.
• Future Trait and Poll-based Async Model — Foundation of async-book/src/ch02-the-future-trait.md and ch03-how-poll-works.md; understanding async in Rust requires grasping the pull-based (Poll) model vs. event-driven callbacks in other languages.
• Executor and Runtime (Tokio, async-std) — Covered in async-book/src/ch07-executors-and-runtimes.md and ch08-tokio-deep-dive.md; learners must distinguish between Future (lazy computation) and Runtime (scheduler/executor)—critical for production async design.
• Pattern Matching and Enum Exhaustiveness — Emphasized in c-cpp-book/src/ch06-enums-and-pattern-matching.md; Rust's algebraic data types and compiler-enforced exhaustive matching replace C++ unions and inheritance hierarchies for safer error handling.

• rust-lang/book — Official 'The Rust Programming Language' book; this training material explicitly builds on and extends it for specialized audiences (C++/JS developers, async deep-dives).
• tokio-rs/tokio — The async runtime and library extensively covered in async-book/ch08-tokio-deep-dive.md; learners will reference tokio's source and docs throughout.
• rust-lang/rust-clippy — Linter and code analyzer ensuring idiomatic Rust; training material implicitly assumes learners will use clippy to validate their exercise solutions.
• rust-lang/rustlings — Interactive small exercises teaching Rust fundamentals; complementary hands-on counterpart to this repo's theoretical deep-dives and capstone projects.
• jonhoo/crust-of-rust — Jon Gjengset's video series (explicitly acknowledged in README inspirations); covers same async/advanced topics with live coding demonstrations alongside this text-based curriculum.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add compilable Rust examples to async-book chapters with cargo test integration

The async-book contains 17 chapters with markdown content but lacks runnable code examples. Each chapter (ch00-ch17) should have accompanying Rust code files that compile and can be tested via cargo test. This ensures code samples stay correct across Rust versions and helps contributors verify their learning. Currently there's no async-book/examples/ directory structure or build validation.

• [ ] Create async-book/examples/ directory with subdirectories for each chapter (ch00/, ch01/, etc.)
• [ ] Extract or create concrete code examples from async-book/src/ch01-why-async-is-different-in-rust.md through ch17-capstone-project.md
• [ ] Add a build.rs or separate Cargo.toml in async-book to validate example compilation
• [ ] Add a GitHub Actions workflow step in .github/workflows/pages.yml to run cargo build --examples to prevent broken code samples in docs

Consolidate and deduplicate ownership/borrowing content across beginner and C++/Java books

The repo has multiple books targeting different audiences (c-cpp-book, csharp-book, etc.) with overlapping foundational content. Currently c-cpp-book has ch07-ownership-and-borrowing.md, ch07-1-lifetimes-and-borrowing-deep-dive.md, and ch07-2-smart-pointers-and-interior-mutability.md (3 files on same topic). A shared 'core-concepts' directory with canonical ownership/borrowing/lifetime explanations could be referenced by all books, reducing maintenance burden and inconsistency.

• [ ] Create a new directory c-cpp-book/src/shared-concepts/ (or similar across books)
• [ ] Identify all duplicate sections in c-cpp-book/src/ch07-*.md and csharp-book equivalents
• [ ] Extract the definitive ownership/borrowing/lifetime content into shared modules
• [ ] Update CONTRIBUTING.md to document this shared content pattern and where new contributors should add ownership-related material

Add missing CI validation for mdBook builds and content quality checks

The repo has .github/workflows/pages.yml for deployment but lacks upstream checks before merge. With multiple books (async-book, c-cpp-book, csharp-book/) each with book.toml, there's no validation that mdbook build succeeds, dead links exist, or missing referenced files (like exercises for ch15-exercises.md in async-book) are caught. This causes broken deployments.

• [ ] Add mdbook CLI installation and mdbook build async-book/, mdbook build c-cpp-book/, mdbook build csharp-book/ to a new GitHub Actions workflow (.github/workflows/mdbook-validate.yml)
• [ ] Add a link-checker step (e.g., lychee or markdown-link-check) to validate no internal cross-references are broken
• [ ] Create a validation script (xtask/src/main.rs already exists as workspace member) to check that all chapter files referenced in SUMMARY.md files actually exist
• [ ] Document in CONTRIBUTING.md the requirement that PRs must pass cargo xtask validate and all mdbook builds

• Add a Mermaid state diagram to async-book/src/ch05-the-state-machine-reveal.md visualizing Future state transitions (Pending → Ready → Polled)—would clarify the invisible compiler-generated state machine concept.
• Expand c-cpp-book/src/ch02-getting-started.md with a side-by-side comparison table: 'C++ iostream → Rust println!', 'vector → Vec', 'std::unique_ptr → Box'—quick reference for C++ developers on first read.
• Create a missing async-book/src/ch15-exercises.md with 3 concrete problems: (1) Implement a custom Future that times out, (2) Build a simple async executor using std::task::Wake, (3) Debug a tokio deadlock scenario—hands-on practice before capstone.

This is a Rust training/educational repository with minimal security risks. The codebase consists primarily of documentation and training materials rather than production code. No hardcoded secrets, exposed credentials, or dangerous dependencies were identified in the provided structure. The workspace uses Rust's cargo system with workspace resolver v2, which is secure by default. The repository maintains proper licensing clarity (MIT + CC-BY-4.0) and includes standard governance files (CODE_OF_CONDUCT.md, CONTRIBUTING.md). The main minor finding is incomplete security policy documentation. As an educational repository, this is appropriate security posture. Regular dependency updates through cargo audit and maintaining the security policy documentation would further strengthen the security posture.

• Low · Incomplete Security Policy Documentation — SECURITY.md. The SECURITY.md file contains only a template/redirect to Microsoft's general security policy without repository-specific vulnerability disclosure procedures or security contacts. Fix: Enhance SECURITY.md with specific vulnerability reporting instructions, response timelines, and contacts for this repository.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.