Add concept index and cross-language notes

Author: lucasbellesi

CONCEPT_INDEX.md

@@ -0,0 +1,73 @@
+# Concept Index
+
+Use this page to browse the same concept across every active language track.
+
+- Use [README.md](README.md) to navigate by language.
+- Use this index to jump directly to the same concept in C++, C#, Go, Python, and TypeScript.
+- Checkpoint links are grouped separately so you can compare level-end projects and assessments side by side.
+
+## Concepts by Level
+
+### 01-foundations
+
+| Concept | C++ | C# | Go | Python | TypeScript |
+| --- | --- | --- | --- | --- | --- |
+| types-and-io | [C++](languages/cpp/01-foundations/types-and-io/README.md) | [C#](languages/csharp/01-foundations/types-and-io/README.md) | [Go](languages/go/01-foundations/types-and-io/README.md) | [Python](languages/python/01-foundations/types-and-io/README.md) | [TypeScript](languages/typescript/01-foundations/types-and-io/README.md) |
+| operators-and-expressions | [C++](languages/cpp/01-foundations/operators-and-expressions/README.md) | [C#](languages/csharp/01-foundations/operators-and-expressions/README.md) | [Go](languages/go/01-foundations/operators-and-expressions/README.md) | [Python](languages/python/01-foundations/operators-and-expressions/README.md) | [TypeScript](languages/typescript/01-foundations/operators-and-expressions/README.md) |
+| control-flow | [C++](languages/cpp/01-foundations/control-flow/README.md) | [C#](languages/csharp/01-foundations/control-flow/README.md) | [Go](languages/go/01-foundations/control-flow/README.md) | [Python](languages/python/01-foundations/control-flow/README.md) | [TypeScript](languages/typescript/01-foundations/control-flow/README.md) |
+| functions | [C++](languages/cpp/01-foundations/functions/README.md) | [C#](languages/csharp/01-foundations/functions/README.md) | [Go](languages/go/01-foundations/functions/README.md) | [Python](languages/python/01-foundations/functions/README.md) | [TypeScript](languages/typescript/01-foundations/functions/README.md) |
+| arrays-and-vectors | [C++](languages/cpp/01-foundations/arrays-and-vectors/README.md) | [C#](languages/csharp/01-foundations/arrays-and-vectors/README.md) | [Go](languages/go/01-foundations/arrays-and-vectors/README.md) | [Python](languages/python/01-foundations/arrays-and-vectors/README.md) | [TypeScript](languages/typescript/01-foundations/arrays-and-vectors/README.md) |
+| strings | [C++](languages/cpp/01-foundations/strings/README.md) | [C#](languages/csharp/01-foundations/strings/README.md) | [Go](languages/go/01-foundations/strings/README.md) | [Python](languages/python/01-foundations/strings/README.md) | [TypeScript](languages/typescript/01-foundations/strings/README.md) |
+| scope-and-lifetime-basics | [C++](languages/cpp/01-foundations/scope-and-lifetime-basics/README.md) | [C#](languages/csharp/01-foundations/scope-and-lifetime-basics/README.md) | [Go](languages/go/01-foundations/scope-and-lifetime-basics/README.md) | [Python](languages/python/01-foundations/scope-and-lifetime-basics/README.md) | [TypeScript](languages/typescript/01-foundations/scope-and-lifetime-basics/README.md) |
+| formatted-output-and-iomanip | [C++](languages/cpp/01-foundations/formatted-output-and-iomanip/README.md) | [C#](languages/csharp/01-foundations/formatted-output-and-iomanip/README.md) | [Go](languages/go/01-foundations/formatted-output-and-iomanip/README.md) | [Python](languages/python/01-foundations/formatted-output-and-iomanip/README.md) | [TypeScript](languages/typescript/01-foundations/formatted-output-and-iomanip/README.md) |
+
+### 02-core
+
+| Concept | C++ | C# | Go | Python | TypeScript |
+| --- | --- | --- | --- | --- | --- |
+| input-validation | [C++](languages/cpp/02-core/input-validation/README.md) | [C#](languages/csharp/02-core/input-validation/README.md) | [Go](languages/go/02-core/input-validation/README.md) | [Python](languages/python/02-core/input-validation/README.md) | [TypeScript](languages/typescript/02-core/input-validation/README.md) |
+| algorithms-basics | [C++](languages/cpp/02-core/algorithms-basics/README.md) | [C#](languages/csharp/02-core/algorithms-basics/README.md) | [Go](languages/go/02-core/algorithms-basics/README.md) | [Python](languages/python/02-core/algorithms-basics/README.md) | [TypeScript](languages/typescript/02-core/algorithms-basics/README.md) |
+| file-io-basics | [C++](languages/cpp/02-core/file-io-basics/README.md) | [C#](languages/csharp/02-core/file-io-basics/README.md) | [Go](languages/go/02-core/file-io-basics/README.md) | [Python](languages/python/02-core/file-io-basics/README.md) | [TypeScript](languages/typescript/02-core/file-io-basics/README.md) |
+| sorting-and-searching | [C++](languages/cpp/02-core/sorting-and-searching/README.md) | [C#](languages/csharp/02-core/sorting-and-searching/README.md) | [Go](languages/go/02-core/sorting-and-searching/README.md) | [Python](languages/python/02-core/sorting-and-searching/README.md) | [TypeScript](languages/typescript/02-core/sorting-and-searching/README.md) |
+| maps-and-frequency-counting | [C++](languages/cpp/02-core/maps-and-frequency-counting/README.md) | [C#](languages/csharp/02-core/maps-and-frequency-counting/README.md) | [Go](languages/go/02-core/maps-and-frequency-counting/README.md) | [Python](languages/python/02-core/maps-and-frequency-counting/README.md) | [TypeScript](languages/typescript/02-core/maps-and-frequency-counting/README.md) |
+| error-handling-and-defensive-programming | [C++](languages/cpp/02-core/error-handling-and-defensive-programming/README.md) | [C#](languages/csharp/02-core/error-handling-and-defensive-programming/README.md) | [Go](languages/go/02-core/error-handling-and-defensive-programming/README.md) | [Python](languages/python/02-core/error-handling-and-defensive-programming/README.md) | [TypeScript](languages/typescript/02-core/error-handling-and-defensive-programming/README.md) |
+
+### 03-advanced
+
+| Concept | C++ | C# | Go | Python | TypeScript |
+| --- | --- | --- | --- | --- | --- |
+| structs-and-classes | [C++](languages/cpp/03-advanced/structs-and-classes/README.md) | [C#](languages/csharp/03-advanced/structs-and-classes/README.md) | [Go](languages/go/03-advanced/structs-and-classes/README.md) | [Python](languages/python/03-advanced/structs-and-classes/README.md) | [TypeScript](languages/typescript/03-advanced/structs-and-classes/README.md) |
+| constructors-and-invariants | [C++](languages/cpp/03-advanced/constructors-and-invariants/README.md) | [C#](languages/csharp/03-advanced/constructors-and-invariants/README.md) | [Go](languages/go/03-advanced/constructors-and-invariants/README.md) | [Python](languages/python/03-advanced/constructors-and-invariants/README.md) | [TypeScript](languages/typescript/03-advanced/constructors-and-invariants/README.md) |
+| copy-and-move-semantics | [C++](languages/cpp/03-advanced/copy-and-move-semantics/README.md) | [C#](languages/csharp/03-advanced/copy-and-move-semantics/README.md) | [Go](languages/go/03-advanced/copy-and-move-semantics/README.md) | [Python](languages/python/03-advanced/copy-and-move-semantics/README.md) | [TypeScript](languages/typescript/03-advanced/copy-and-move-semantics/README.md) |
+| inheritance-and-polymorphism | [C++](languages/cpp/03-advanced/inheritance-and-polymorphism/README.md) | [C#](languages/csharp/03-advanced/inheritance-and-polymorphism/README.md) | [Go](languages/go/03-advanced/inheritance-and-polymorphism/README.md) | [Python](languages/python/03-advanced/inheritance-and-polymorphism/README.md) | [TypeScript](languages/typescript/03-advanced/inheritance-and-polymorphism/README.md) |
+| templates-basics | [C++](languages/cpp/03-advanced/templates-basics/README.md) | [C#](languages/csharp/03-advanced/templates-basics/README.md) | [Go](languages/go/03-advanced/templates-basics/README.md) | [Python](languages/python/03-advanced/templates-basics/README.md) | [TypeScript](languages/typescript/03-advanced/templates-basics/README.md) |
+
+### 04-expert
+
+| Concept | C++ | C# | Go | Python | TypeScript |
+| --- | --- | --- | --- | --- | --- |
+| memory-management-and-raii | [C++](languages/cpp/04-expert/memory-management-and-raii/README.md) | [C#](languages/csharp/04-expert/memory-management-and-raii/README.md) | [Go](languages/go/04-expert/memory-management-and-raii/README.md) | [Python](languages/python/04-expert/memory-management-and-raii/README.md) | [TypeScript](languages/typescript/04-expert/memory-management-and-raii/README.md) |
+| smart-pointers-in-depth | [C++](languages/cpp/04-expert/smart-pointers-in-depth/README.md) | [C#](languages/csharp/04-expert/smart-pointers-in-depth/README.md) | [Go](languages/go/04-expert/smart-pointers-in-depth/README.md) | [Python](languages/python/04-expert/smart-pointers-in-depth/README.md) | [TypeScript](languages/typescript/04-expert/smart-pointers-in-depth/README.md) |
+| concurrency-basics | [C++](languages/cpp/04-expert/concurrency-basics/README.md) | [C#](languages/csharp/04-expert/concurrency-basics/README.md) | [Go](languages/go/04-expert/concurrency-basics/README.md) | [Python](languages/python/04-expert/concurrency-basics/README.md) | [TypeScript](languages/typescript/04-expert/concurrency-basics/README.md) |
+| performance-and-profiling-basics | [C++](languages/cpp/04-expert/performance-and-profiling-basics/README.md) | [C#](languages/csharp/04-expert/performance-and-profiling-basics/README.md) | [Go](languages/go/04-expert/performance-and-profiling-basics/README.md) | [Python](languages/python/04-expert/performance-and-profiling-basics/README.md) | [TypeScript](languages/typescript/04-expert/performance-and-profiling-basics/README.md) |
+| modularization-and-build-structure | [C++](languages/cpp/04-expert/modularization-and-build-structure/README.md) | [C#](languages/csharp/04-expert/modularization-and-build-structure/README.md) | [Go](languages/go/04-expert/modularization-and-build-structure/README.md) | [Python](languages/python/04-expert/modularization-and-build-structure/README.md) | [TypeScript](languages/typescript/04-expert/modularization-and-build-structure/README.md) |
+
+## Checkpoints by Level
+
+### Projects
+
+| Level | C++ | C# | Go | Python | TypeScript |
+| --- | --- | --- | --- | --- | --- |
+| 01-foundations | [C++](languages/cpp/projects/01-foundations/README.md) | [C#](languages/csharp/projects/01-foundations/README.md) | [Go](languages/go/projects/01-foundations/README.md) | [Python](languages/python/projects/01-foundations/README.md) | [TypeScript](languages/typescript/projects/01-foundations/README.md) |
+| 02-core | [C++](languages/cpp/projects/02-core/README.md) | [C#](languages/csharp/projects/02-core/README.md) | [Go](languages/go/projects/02-core/README.md) | [Python](languages/python/projects/02-core/README.md) | [TypeScript](languages/typescript/projects/02-core/README.md) |
+| 03-advanced | [C++](languages/cpp/projects/03-advanced/README.md) | [C#](languages/csharp/projects/03-advanced/README.md) | [Go](languages/go/projects/03-advanced/README.md) | [Python](languages/python/projects/03-advanced/README.md) | [TypeScript](languages/typescript/projects/03-advanced/README.md) |
+| 04-expert | [C++](languages/cpp/projects/04-expert/README.md) | [C#](languages/csharp/projects/04-expert/README.md) | [Go](languages/go/projects/04-expert/README.md) | [Python](languages/python/projects/04-expert/README.md) | [TypeScript](languages/typescript/projects/04-expert/README.md) |
+
+### Assessments
+
+| Level | C++ | C# | Go | Python | TypeScript |
+| --- | --- | --- | --- | --- | --- |
+| 01-foundations | [C++](languages/cpp/assessments/01-foundations/README.md) | [C#](languages/csharp/assessments/01-foundations/README.md) | [Go](languages/go/assessments/01-foundations/README.md) | [Python](languages/python/assessments/01-foundations/README.md) | [TypeScript](languages/typescript/assessments/01-foundations/README.md) |
+| 02-core | [C++](languages/cpp/assessments/02-core/README.md) | [C#](languages/csharp/assessments/02-core/README.md) | [Go](languages/go/assessments/02-core/README.md) | [Python](languages/python/assessments/02-core/README.md) | [TypeScript](languages/typescript/assessments/02-core/README.md) |
+| 03-advanced | [C++](languages/cpp/assessments/03-advanced/README.md) | [C#](languages/csharp/assessments/03-advanced/README.md) | [Go](languages/go/assessments/03-advanced/README.md) | [Python](languages/python/assessments/03-advanced/README.md) | [TypeScript](languages/typescript/assessments/03-advanced/README.md) |
+| 04-expert | [C++](languages/cpp/assessments/04-expert/README.md) | [C#](languages/csharp/assessments/04-expert/README.md) | [Go](languages/go/assessments/04-expert/README.md) | [Python](languages/python/assessments/04-expert/README.md) | [TypeScript](languages/typescript/assessments/04-expert/README.md) |

CONTRIBUTING.md

@@ -73,6 +73,7 @@ The public PowerShell and Bash scripts are thin wrappers over the shared Python
 - New concept modules should follow the existing folder layout.
 - Every concept README in implemented levels should include:
   - required `## Learning Metadata` before `## Quick Run` with `Difficulty`, `Estimated Time`, `Prerequisites`, and `Cross-Language Lens`
+  - recommended `## Cross-Language Notes` after `## Common Pitfalls` and before `## Exercise Focus`
   - `## Quick Run`
   - `## Topics Covered`
   - `## Common Pitfalls`
@@ -84,6 +85,7 @@ The public PowerShell and Bash scripts are thin wrappers over the shared Python
   - runnable entrypoint (`main.cs` + `.csproj`, `main.go`, `main.py`, or `main.ts`)
   - the same learner goal, input/output shape, and acceptance expectations as the corresponding C++ checkpoint
   - required `## Learning Metadata` before `## Quick Run` with `Difficulty`, `Estimated Time`, `Prerequisites`, and `Learning Focus`
+  - recommended `## Cross-Language Notes` before `## What To Check`
 - Every implemented level README should include required `## Learning Metadata` before `## Module Order` with `Difficulty`, `Estimated Time`, `Prerequisites`, and `Study Strategy`.
 - Checkpoint README structure should mirror the matching C++ checkpoint style, not the module README contract.
 - Every `example/main.*` file should include intent-first comments for:
@@ -100,6 +102,7 @@ The public PowerShell and Bash scripts are thin wrappers over the shared Python
 - Keep documentation in English and keep path names consistent with folder names.
 - Keep parity planning updated in `LANGUAGE_PARITY_MATRIX.md` when adding modules or checkpoints to non-C++ tracks.
 - Keep root and language README status sections aligned with project and assessment coverage when those directories change.
+- Keep [CONCEPT_INDEX.md](CONCEPT_INDEX.md) aligned with any new or renamed module/checkpoint paths.
 
 ## Commit Messages
 

README.md

@@ -57,6 +57,7 @@ If you only want to learn one track, follow that track README first because lang
 | TypeScript | 01-foundations, 02-core, 03-advanced, 04-expert | 8/8 foundations modules, 6/6 core modules, 5/5 advanced modules, 5/5 expert modules, 4/4 projects, 4/4 assessments | Module and checkpoint parity complete through expert |
 
 Parity planning reference: [LANGUAGE_PARITY_MATRIX.md](LANGUAGE_PARITY_MATRIX.md)
+Browse by concept: [CONCEPT_INDEX.md](CONCEPT_INDEX.md)
 
 ## Run One Example Per Language
 
@@ -127,6 +128,8 @@ A standardized `## Learning Metadata` block is required before `## Quick Run` fo
 - checkpoints: difficulty, estimated time, prerequisites, learning focus
 - level READMEs: difficulty, estimated time, prerequisites, study strategy
 
+`## Cross-Language Notes` is the recommended comparison section for new or substantially updated modules and checkpoints. Keep it short, concrete, and honest about where concepts do not map one-to-one.
+
 Checkpoint artifacts under `languages/<language>/projects/*` and `languages/<language>/assessments/*` should mirror the corresponding C++ checkpoint style:
 
 - `README.md`
@@ -173,6 +176,8 @@ The public PowerShell and Bash scripts remain the supported entrypoints, but the
 
 The multi-language smoke scripts also compile standalone C# exercises by generating temporary validation projects during the check and compile TypeScript programs before executing their smoke targets.
 
+Documentation sync also validates that [CONCEPT_INDEX.md](CONCEPT_INDEX.md) covers every implemented module and checkpoint path listed in the automation manifest.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution workflow and documentation requirements.

languages/cpp/04-expert/concurrency-basics/README.md

@@ -36,6 +36,12 @@ On Linux, `-pthread` is required for thread support.
 - Forgetting to join threads before program exit.
 - Waiting on condition variables without a predicate.
 
+## Cross-Language Notes
+
+- This version is the thread-and-mutex baseline for the repo.
+- Other tracks keep the same coordination goals but use very different runtime primitives such as goroutines, tasks, threads under the GIL, or promises.
+- Compare the cost of explicit synchronization here with the safer defaults in higher-level runtimes.
+
 ## Exercise Focus
 
 - `exercises/01.cpp`: parallel chunk sum with worker threads.
@@ -59,3 +65,4 @@ On Linux, `-pthread` is required for thread support.
 - [ ] I can protect critical sections with a mutex.
 - [ ] I can coordinate producers and consumers correctly.
 - [ ] I completed both exercises.
+

languages/cpp/04-expert/memory-management-and-raii/README.md

@@ -34,6 +34,12 @@ g++ -std=c++17 -Wall -Wextra -pedantic example/main.cpp -o memory_raii_example
 - Attempting to copy `unique_ptr`.
 - Mixing ownership and non-ownership pointers incorrectly.
 
+## Cross-Language Notes
+
+- This is the canonical RAII version: cleanup is tied to scope exit through destructors.
+- Compare this with C#, Python, Go, and TypeScript, where resource cleanup is explicit even when memory is managed.
+- The transferable idea is lifetime discipline, not the exact destructor syntax.
+
 ## Exercise Focus
 
 - `exercises/01.cpp`: dynamic array with `std::unique_ptr<int[]>`.
@@ -57,3 +63,4 @@ g++ -std=c++17 -Wall -Wextra -pedantic example/main.cpp -o memory_raii_example
 - [ ] I can use `unique_ptr` for owned dynamic memory.
 - [ ] I can design classes with cleanup in destructors.
 - [ ] I completed both exercises.
+

languages/cpp/04-expert/modularization-and-build-structure/README.md

@@ -34,6 +34,12 @@ g++ -std=c++17 -Wall -Wextra -pedantic example/main.cpp -o modularization_exampl
 - Circular includes.
 - Missing declarations for used symbols.
 
+## Cross-Language Notes
+
+- C++ is the canonical header/source split, so it anchors how the repo thinks about multi-file structure.
+- Other tracks keep the same separation goals but express them with imports, packages, projects, or namespaces.
+- The comparison to watch is not syntax, but where each language chooses to expose public boundaries.
+
 ## Exercise Focus
 
 - `exercises/01.cpp`: refactor procedural code into module-like sections.
@@ -57,3 +63,4 @@ g++ -std=c++17 -Wall -Wextra -pedantic example/main.cpp -o modularization_exampl
 - [ ] I can design reusable helper utilities.
 - [ ] I can explain how multi-file builds are assembled.
 - [ ] I completed both exercises.
+

languages/cpp/04-expert/performance-and-profiling-basics/README.md

@@ -34,6 +34,12 @@ g++ -std=c++17 -Wall -Wextra -pedantic example/main.cpp -o performance_profiling
 - Drawing conclusions from one run.
 - Ignoring algorithmic complexity.
 
+## Cross-Language Notes
+
+- C++ is the lowest-level performance baseline in the repo, so its examples map most directly to memory layout and native execution costs.
+- Other tracks keep the same measurement discipline but add runtime effects such as garbage collection, interpreter overhead, or JIT behavior.
+- Use this module as the reference point for what later tracks are abstracting away.
+
 ## Exercise Focus
 
 - `exercises/01.cpp`: compare pass-by-value vs const-reference.
@@ -57,3 +63,4 @@ g++ -std=c++17 -Wall -Wextra -pedantic example/main.cpp -o performance_profiling
 - [ ] I can compare two implementations fairly.
 - [ ] I can justify simple optimization choices.
 - [ ] I completed both exercises.
+