Sync docs and metadata from problem-specs

exercises/practice/anagram/.docs/instructions.md

@@ -1,13 +1,12 @@
 # Instructions
 
-Your task is to, given a target word and a set of candidate words, to find the subset of the candidates that are anagrams of the target.
+Given a target word and one or more candidate words, your task is to find the candidates that are anagrams of the target.
 
 An anagram is a rearrangement of letters to form a new word: for example `"owns"` is an anagram of `"snow"`.
 A word is _not_ its own anagram: for example, `"stop"` is not an anagram of `"stop"`.
 
-The target and candidates are words of one or more ASCII alphabetic characters (`A`-`Z` and `a`-`z`).
-Lowercase and uppercase characters are equivalent: for example, `"PoTS"` is an anagram of `"sTOp"`, but `StoP` is not an anagram of `sTOp`.
-The anagram set is the subset of the candidate set that are anagrams of the target (in any order).
-Words in the anagram set should have the same letter case as in the candidate set.
+The target word and candidate words are made up of one or more ASCII alphabetic characters (`A`-`Z` and `a`-`z`).
+Lowercase and uppercase characters are equivalent: for example, `"PoTS"` is an anagram of `"sTOp"`, but `"StoP"` is not an anagram of `"sTOp"`.
+The words you need to find should be taken from the candidate words, using the same letter case.
 
-Given the target `"stone"` and candidates `"stone"`, `"tones"`, `"banana"`, `"tons"`, `"notes"`, `"Seton"`, the anagram set is `"tones"`, `"notes"`, `"Seton"`.
+Given the target `"stone"` and the candidate words `"stone"`, `"tones"`, `"banana"`, `"tons"`, `"notes"`, and `"Seton"`, the anagram words you need to find are `"tones"`, `"notes"`, and `"Seton"`.

exercises/practice/binary-search-tree/.docs/instructions.md

@@ -19,29 +19,52 @@ All data in the left subtree is less than or equal to the current node's data, a
 
 For example, if we had a node containing the data 4, and we added the data 2, our tree would look like this:
 
+![A graph with root node 4 and a single child node 2.](https://assets.exercism.org/images/exercises/binary-search-tree/tree-4-2.svg)
+
+```text
       4
      /
     2
+```
 
 If we then added 6, it would look like this:
 
+![A graph with root node 4 and two child nodes 2 and 6.](https://assets.exercism.org/images/exercises/binary-search-tree/tree-4-2-6.svg)
+
+```text
       4
      / \
     2   6
+```
 
 If we then added 3, it would look like this
 
+![A graph with root node 4, two child nodes 2 and 6, and a grandchild node 3.](https://assets.exercism.org/images/exercises/binary-search-tree/tree-4-2-6-3.svg)
+
+```text
        4
      /   \
     2     6
      \
       3
+```
 
 And if we then added 1, 5, and 7, it would look like this
 
+![A graph with root node 4, two child nodes 2 and 6, and four grandchild nodes 1, 3, 5 and 7.](https://assets.exercism.org/images/exercises/binary-search-tree/tree-4-2-6-1-3-5-7.svg)
+
+```text
           4
         /   \
        /     \
       2       6
      / \     / \
     1   3   5   7
+```
+
+## Credit
+
+The images were created by [habere-et-dispertire][habere-et-dispertire] using [PGF/TikZ][pgf-tikz] by Till Tantau.
+
+[habere-et-dispertire]: https://exercism.org/profiles/habere-et-dispertire
+[pgf-tikz]: https://en.wikipedia.org/wiki/PGF/TikZ

exercises/practice/dominoes/.docs/instructions.md

@@ -2,7 +2,9 @@
 
 Make a chain of dominoes.
 
-Compute a way to order a given set of dominoes in such a way that they form a correct domino chain (the dots on one half of a stone match the dots on the neighboring half of an adjacent stone) and that dots on the halves of the stones which don't have a neighbor (the first and last stone) match each other.
+Compute a way to order a given set of domino stones so that they form a correct domino chain.
+In the chain, the dots on one half of a stone must match the dots on the neighboring half of an adjacent stone.
+Additionally, the dots on the halves of the stones without neighbors (the first and last stone) must match each other.
 
 For example given the stones `[2|1]`, `[2|3]` and `[1|3]` you should compute something
 like `[1|2] [2|3] [3|1]` or `[3|2] [2|1] [1|3]` or `[1|3] [3|2] [2|1]` etc, where the first and last numbers are the same.

exercises/practice/dominoes/.docs/introduction.md

@@ -0,0 +1,13 @@
+# Introduction
+
+In Toyland, the trains are always busy delivering treasures across the city, from shiny marbles to rare building blocks.
+The tracks they run on are made of colorful domino-shaped pieces, each marked with two numbers.
+For the trains to move, the dominoes must form a perfect chain where the numbers match.
+
+Today, an urgent delivery of rare toys is on hold.
+You've been handed a set of track pieces to inspect.
+If they can form a continuous chain, the train will be on its way, bringing smiles across Toyland.
+If not, the set will be discarded, and another will be tried.
+
+The toys are counting on you to solve this puzzle.
+Will the dominoes connect the tracks and send the train rolling, or will the set be left behind?

exercises/practice/flatten-array/.docs/instructions.md

@@ -1,11 +1,16 @@
 # Instructions
 
-Take a nested list and return a single flattened list with all values except nil/null.
+Take a nested array of any depth and return a fully flattened array.
 
-The challenge is to take an arbitrarily-deep nested list-like structure and produce a flattened structure without any nil/null values.
+Note that some language tracks may include null-like values in the input array, and the way these values are represented varies by track.
+Such values should be excluded from the flattened array.
 
-For example:
+Additionally, the input may be of a different data type and contain different types, depending on the track.
 
-input: [1,[2,3,null,4],[null],5]
+Check the test suite for details.
 
-output: [1,2,3,4,5]
+## Example
+
+input: `[1, [2, 6, null], [[null, [4]], 5]]`
+
+output: `[1, 2, 6, 4, 5]`

exercises/practice/flatten-array/.docs/introduction.md

@@ -0,0 +1,7 @@
+# Introduction
+
+A shipment of emergency supplies has arrived, but there's a problem.
+To protect from damage, the items — flashlights, first-aid kits, blankets — are packed inside boxes, and some of those boxes are nested several layers deep inside other boxes!
+
+To be prepared for an emergency, everything must be easily accessible in one box.
+Can you unpack all the supplies and place them into a single box, so they're ready when needed most?

exercises/practice/grains/.docs/instructions.md

@@ -1,15 +1,11 @@
 # Instructions
 
-Calculate the number of grains of wheat on a chessboard given that the number on each square doubles.
+Calculate the number of grains of wheat on a chessboard.
 
-There once was a wise servant who saved the life of a prince.
-The king promised to pay whatever the servant could dream up.
-Knowing that the king loved chess, the servant told the king he would like to have grains of wheat.
-One grain on the first square of a chess board, with the number of grains doubling on each successive square.
+A chessboard has 64 squares.
+Square 1 has one grain, square 2 has two grains, square 3 has four grains, and so on, doubling each time.
 
-There are 64 squares on a chessboard (where square 1 has one grain, square 2 has two grains, and so on).
+Write code that calculates:
 
-Write code that shows:
-
-- how many grains were on a given square, and
+- the number of grains on a given square
 - the total number of grains on the chessboard

exercises/practice/grains/.docs/introduction.md

@@ -0,0 +1,6 @@
+# Introduction
+
+There once was a wise servant who saved the life of a prince.
+The king promised to pay whatever the servant could dream up.
+Knowing that the king loved chess, the servant told the king he would like to have grains of wheat.
+One grain on the first square of a chessboard, with the number of grains doubling on each successive square.

exercises/practice/grains/.meta/config.json

@@ -25,5 +25,5 @@
   },
   "blurb": "Calculate the number of grains of wheat on a chessboard given that the number on each square doubles.",
   "source": "The CodeRanch Cattle Drive, Assignment 6",
-  "source_url": "https://coderanch.com/wiki/718824/Grains"
+  "source_url": "https://web.archive.org/web/20240908084142/https://coderanch.com/wiki/718824/Grains"
 }

exercises/practice/knapsack/.docs/instructions.md

@@ -1,11 +1,11 @@
 # Instructions
 
-Your task is to determine which items to take so that the total value of his selection is maximized, taking into account the knapsack's carrying capacity.
+Your task is to determine which items to take so that the total value of her selection is maximized, taking into account the knapsack's carrying capacity.
 
 Items will be represented as a list of items.
 Each item will have a weight and value.
 All values given will be strictly positive.
-Bob can take only one of each item.
+Lhakpa can take only one of each item.
 
 For example:
 
@@ -21,5 +21,5 @@ Knapsack Maximum Weight: 10
 ```
 
 For the above, the first item has weight 5 and value 10, the second item has weight 4 and value 40, and so on.
-In this example, Bob should take the second and fourth item to maximize his value, which, in this case, is 90.
-He cannot get more than 90 as his knapsack has a weight limit of 10.
+In this example, Lhakpa should take the second and fourth item to maximize her value, which, in this case, is 90.
+She cannot get more than 90 as her knapsack has a weight limit of 10.

exercises/practice/knapsack/.docs/introduction.md

@@ -1,8 +1,10 @@
 # Introduction
 
-Bob is a thief.
-After months of careful planning, he finally manages to crack the security systems of a fancy store.
+Lhakpa is a [Sherpa][sherpa] mountain guide and porter.
+After months of careful planning, the expedition Lhakpa works for is about to leave.
+She will be paid the value she carried to the base camp.
 
-In front of him are many items, each with a value and weight.
-Bob would gladly take all of the items, but his knapsack can only hold so much weight.
-Bob has to carefully consider which items to take so that the total value of his selection is maximized.
+In front of her are many items, each with a value and weight.
+Lhakpa would gladly take all of the items, but her knapsack can only hold so much weight.
+
+[sherpa]: https://en.wikipedia.org/wiki/Sherpa_people#Mountaineering

exercises/practice/leap/.meta/config.json

@@ -24,5 +24,5 @@
   },
   "blurb": "Determine whether a given year is a leap year.",
   "source": "CodeRanch Cattle Drive, Assignment 3",
-  "source_url": "https://coderanch.com/t/718816/Leap"
+  "source_url": "https://web.archive.org/web/20240907033714/https://coderanch.com/t/718816/Leap"
 }

exercises/practice/luhn/.docs/instructions.md

@@ -1,65 +1,68 @@
 # Instructions
 
-Given a number determine whether or not it is valid per the Luhn formula.
+Determine whether a number is valid according to the [Luhn formula][luhn].
 
-The [Luhn algorithm][luhn] is a simple checksum formula used to validate a variety of identification numbers, such as credit card numbers and Canadian Social Insurance Numbers.
+The number will be provided as a string.
 
-The task is to check if a given string is valid.
-
-## Validating a Number
+## Validating a number
 
 Strings of length 1 or less are not valid.
 Spaces are allowed in the input, but they should be stripped before checking.
 All other non-digit characters are disallowed.
 
-### Example 1: valid credit card number
+## Examples
 
-```text
-4539 3195 0343 6467
-```
+### Valid credit card number
 
-The first step of the Luhn algorithm is to double every second digit, starting from the right.
-We will be doubling
+The number to be checked is `4539 3195 0343 6467`.
+
+The first step of the Luhn algorithm is to start at the end of the number and double every second digit, beginning with the second digit from the right and moving left.
 
 ```text
 4539 3195 0343 6467
 ↑ ↑  ↑ ↑  ↑ ↑  ↑ ↑  (double these)
 ```
 
-If doubling the number results in a number greater than 9 then subtract 9 from the product.
-The results of our doubling:
+If the result of doubling a digit is greater than 9, we subtract 9 from that result.
+We end up with:
 
 ```text
 8569 6195 0383 3437
 ```
 
-Then sum all of the digits:
+Finally, we sum all digits.
+If the sum is evenly divisible by 10, the original number is valid.
 
 ```text
-8+5+6+9+6+1+9+5+0+3+8+3+3+4+3+7 = 80
+8 + 5 + 6 + 9 + 6 + 1 + 9 + 5 + 0 + 3 + 8 + 3 + 3 + 4 + 3 + 7 = 80
 ```
 
-If the sum is evenly divisible by 10, then the number is valid.
-This number is valid!
+80 is evenly divisible by 10, so number `4539 3195 0343 6467` is valid!
+
+### Invalid Canadian SIN
+
+The number to be checked is `066 123 478`.
 
-### Example 2: invalid credit card number
+We start at the end of the number and double every second digit, beginning with the second digit from the right and moving left.
 
 ```text
-8273 1232 7352 0569
+066 123 478
+ ↑  ↑ ↑  ↑  (double these)
 ```
 
-Double the second digits, starting from the right
+If the result of doubling a digit is greater than 9, we subtract 9 from that result.
+We end up with:
 
 ```text
-7253 2262 5312 0539
+036 226 458
 ```
 
-Sum the digits
+We sum the digits:
 
 ```text
-7+2+5+3+2+2+6+2+5+3+1+2+0+5+3+9 = 57
+0 + 3 + 6 + 2 + 2 + 6 + 4 + 5 + 8 = 36
 ```
 
-57 is not evenly divisible by 10, so this number is not valid.
+36 is not evenly divisible by 10, so number `066 123 478` is not valid!
 
 [luhn]: https://en.wikipedia.org/wiki/Luhn_algorithm

exercises/practice/luhn/.docs/introduction.md

@@ -0,0 +1,11 @@
+# Introduction
+
+At the Global Verification Authority, you've just been entrusted with a critical assignment.
+Across the city, from online purchases to secure logins, countless operations rely on the accuracy of numerical identifiers like credit card numbers, bank account numbers, transaction codes, and tracking IDs.
+The Luhn algorithm is a simple checksum formula used to help identify mistyped numbers.
+
+A batch of identifiers has just arrived on your desk.
+All of them must pass the Luhn test to ensure they're legitimate.
+If any fail, they'll be flagged as invalid, preventing mistakes such as incorrect transactions or failed account verifications.
+
+Can you ensure this is done right? The integrity of many services depends on you.

exercises/practice/meetup/.docs/instructions.md

@@ -2,7 +2,7 @@
 
 Your task is to find the exact date of a meetup, given a month, year, weekday and week.
 
-There are five week values to consider: `first`, `second`, `third`, `fourth`, `last`, `teenth`.
+There are six week values to consider: `first`, `second`, `third`, `fourth`, `last`, `teenth`.
 
 For example, you might be asked to find the date for the meetup on the first Monday in January 2018 (January 1, 2018).
 

exercises/practice/pascals-triangle/.docs/introduction.md

@@ -13,7 +13,7 @@ Over the next hour, your teacher reveals some amazing things hidden in this tria
 - It contains the Fibonacci sequence.
 - If you color odd and even numbers differently, you get a beautiful pattern called the [Sierpiński triangle][wikipedia-sierpinski-triangle].
 
-The teacher implores you and your classmates to lookup other uses, and assures you that there are lots more!
+The teacher implores you and your classmates to look up other uses, and assures you that there are lots more!
 At that moment, the school bell rings.
 You realize that for the past hour, you were completely absorbed in learning about Pascal's triangle.
 You quickly grab your laptop from your bag and go outside, ready to enjoy both the sunshine _and_ the wonders of Pascal's triangle.

exercises/practice/phone-number/.docs/instructions.md

@@ -1,6 +1,6 @@
 # Instructions
 
-Clean up user-entered phone numbers so that they can be sent SMS messages.
+Clean up phone numbers so that they can be sent SMS messages.
 
 The **North American Numbering Plan (NANP)** is a telephone numbering system used by many countries in North America like the United States, Canada or Bermuda.
 All NANP-countries share the same international country code: `1`.

exercises/practice/phone-number/.docs/introduction.md

@@ -0,0 +1,12 @@
+# Introduction
+
+You've joined LinkLine, a leading communications company working to ensure reliable connections for everyone.
+The team faces a big challenge: users submit phone numbers in all sorts of formats — dashes, spaces, dots, parentheses, and even prefixes.
+Some numbers are valid, while others are impossible to use.
+
+Your mission is to turn this chaos into order.
+You'll clean up valid numbers, formatting them appropriately for use in the system.
+At the same time, you'll identify and filter out any invalid entries.
+
+The success of LinkLine's operations depends on your ability to separate the useful from the unusable.
+Are you ready to take on the challenge and keep the connections running smoothly?