🤖 Auto-sync docs, metadata, and filepaths

Author: github-actions[bot]

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/luhn/.docs/instructions.md

@@ -41,7 +41,7 @@ If the sum is evenly divisible by 10, the original number is valid.
 
 ### Invalid Canadian SIN
 
-The number to be checked is `066 123 468`.
+The number to be checked is `066 123 478`.
 
 We start at the end of the number and double every second digit, beginning with the second digit from the right and moving left.
 

exercises/practice/protein-translation/.docs/instructions.md

@@ -1,36 +1,17 @@
 # Instructions
 
-Translate RNA sequences into proteins.
+Your job is to translate RNA sequences into proteins.
 
-RNA can be broken into three-nucleotide sequences called codons, and then translated to a protein like so:
+RNA strands are made up of three-nucleotide sequences called **codons**.
+Each codon translates to an **amino acid**.
+When joined together, those amino acids make a protein.
 
-RNA: `"AUGUUUUCU"` => translates to
-
-Codons: `"AUG", "UUU", "UCU"`
-=> which become a protein with the following sequence =>
-
-Protein: `"Methionine", "Phenylalanine", "Serine"`
-
-There are 64 codons which in turn correspond to 20 amino acids; however, all of the codon sequences and resulting amino acids are not important in this exercise.
-If it works for one codon, the program should work for all of them.
-However, feel free to expand the list in the test suite to include them all.
-
-There are also three terminating codons (also known as 'STOP' codons); if any of these codons are encountered (by the ribosome), all translation ends and the protein is terminated.
-
-All subsequent codons after are ignored, like this:
-
-RNA: `"AUGUUUUCUUAAAUG"` =>
-
-Codons: `"AUG", "UUU", "UCU", "UAA", "AUG"` =>
-
-Protein: `"Methionine", "Phenylalanine", "Serine"`
-
-Note the stop codon `"UAA"` terminates the translation and the final methionine is not translated into the protein sequence.
-
-Below are the codons and resulting amino acids needed for the exercise.
+In the real world, there are 64 codons, which in turn correspond to 20 amino acids.
+However, for this exercise, you’ll only use a few of the possible 64.
+They are listed below:
 
 | Codon              | Amino Acid    |
-| :----------------- | :------------ |
+| ------------------ | ------------- |
 | AUG                | Methionine    |
 | UUU, UUC           | Phenylalanine |
 | UUA, UUG           | Leucine       |
@@ -40,6 +21,18 @@ Below are the codons and resulting amino acids needed for the exercise.
 | UGG                | Tryptophan    |
 | UAA, UAG, UGA      | STOP          |
 
+For example, the RNA string “AUGUUUUCU” has three codons: “AUG”, “UUU” and “UCU”.
+These map to Methionine, Phenylalanine, and Serine.
+
+## “STOP” Codons
+
+You’ll note from the table above that there are three **“STOP” codons**.
+If you encounter any of these codons, ignore the rest of the sequence — the protein is complete.
+
+For example, “AUGUUUUCUUAAAUG” contains a STOP codon (“UAA”).
+Once we reach that point, we stop processing.
+We therefore only consider the part before it (i.e. “AUGUUUUCU”), not any further codons after it (i.e. “AUG”).
+
 Learn more about [protein translation on Wikipedia][protein-translation].
 
 [protein-translation]: https://en.wikipedia.org/wiki/Translation_(biology)

exercises/practice/relative-distance/.docs/instructions.md

@@ -1,6 +1,7 @@
 # Instructions
 
 Your task is to determine the degree of separation between two individuals in a family tree.
+This is similar to the pop culture idea that every Hollywood actor is [within six degrees of Kevin Bacon][six-bacons].
 
 - You will be given an input, with all parent names and their children.
 - Each name is unique, a child _can_ have one or two parents.
@@ -13,27 +14,26 @@ Your task is to determine the degree of separation between two individuals in a
 Given the following family tree:
 
 ```text
-      ┌──────────┐            ┌──────────┐ ┌───────────┐
-      │  Helena  │            │  Erdős   │ │  Shusaku  │
-      └───┬───┬──┘            └─────┬────┘ └──────┬────┘
-      ┌───┘   └───────┐             └──────┬──────┘
-      ▼               ▼                    ▼
-┌──────────┐     ┌────────┐          ┌──────────┐
-│   Isla   │     │  Tariq │          │   Kevin  │
-└────┬─────┘     └────┬───┘          └──────────┘
-     ▼                ▼
-┌─────────┐      ┌────────┐
+      ┌──────────┐            ┌──────────┐     ┌───────────┐
+      │  Helena  │            │  Erdős   ├─────┤  Shusaku  │
+      └───┬───┬──┘            └─────┬────┘     └────┬──────┘
+      ┌───┘   └───────┐             └───────┬───────┘
+┌─────┴────┐     ┌────┴───┐           ┌─────┴────┐
+│   Isla   ├─────┤ Tariq  │           │   Kevin  │
+└────┬─────┘     └────┬───┘           └──────────┘
+     │                │
+┌────┴────┐      ┌────┴───┐
 │   Uma   │      │ Morphy │
 └─────────┘      └────────┘
 ```
 
-The degree of separation between Tariq and Uma is 3 (Tariq → Helena → Isla → Uma).
-There's no known relationship between Isla and [Kevin][six-bacons], as there is no connection in the given data.
+The degree of separation between Tariq and Uma is 2 (Tariq → Isla → Uma).
+There's no known relationship between Isla and Kevin, as there is no connection in the given data.
 The degree of separation between Uma and Isla is 1.
 
-```exercism/note
+~~~~exercism/note
 Isla and Tariq are siblings and have a separation of 1.
 Similarly, this implementation would report a separation of 2 from you to your father's brother.
-```
+~~~~
 
 [six-bacons]: https://en.m.wikipedia.org/wiki/Six_Degrees_of_Kevin_Bacon

exercises/practice/relative-distance/.docs/introduction.md

@@ -9,4 +9,4 @@ Your algorithm will determine the **degree of separation** between two individua
 
 Will your app help crown a perfect match?
 
-[islendiga-app]: http://www.islendingaapp.is/information-in-english/
+[islendiga-app]: https://web.archive.org/web/20250816223614/http://www.islendingaapp.is/information-in-english/

exercises/practice/say/.docs/instructions.md

@@ -1,48 +1,12 @@
 # Instructions
 
-Given a number from 0 to 999,999,999,999, spell out that number in English.
+Given a number, your task is to express it in English words exactly as your friend should say it out loud.
+Yaʻqūb expects to use numbers from 0 up to 999,999,999,999.
 
-## Step 1
+Examples:
 
-Handle the basic case of 0 through 99.
-
-If the input to the program is `22`, then the output should be `'twenty-two'`.
-
-Your program should complain loudly if given a number outside the blessed range.
-
-Some good test cases for this program are:
-
-- 0
-- 14
-- 50
-- 98
-- -1
-- 100
-
-### Extension
-
-If you're on a Mac, shell out to Mac OS X's `say` program to talk out loud.
-If you're on Linux or Windows, eSpeakNG may be available with the command `espeak`.
-
-## Step 2
-
-Implement breaking a number up into chunks of thousands.
-
-So `1234567890` should yield a list like 1, 234, 567, and 890, while the far simpler `1000` should yield just 1 and 0.
-
-## Step 3
-
-Now handle inserting the appropriate scale word between those chunks.
-
-So `1234567890` should yield `'1 billion 234 million 567 thousand 890'`
-
-The program must also report any values that are out of range.
-It's fine to stop at "trillion".
-
-## Step 4
-
-Put it all together to get nothing but plain English.
-
-`12345` should give `twelve thousand three hundred forty-five`.
-
-The program must also report any values that are out of range.
+- 0 → zero
+- 1 → one
+- 12 → twelve
+- 123 → one hundred twenty-three
+- 1,234 → one thousand two hundred thirty-four

exercises/practice/say/.docs/introduction.md

@@ -0,0 +1,6 @@
+# Introduction
+
+Your friend Yaʻqūb works the counter at the busiest deli in town, slicing, weighing, and wrapping orders for a never-ending line of hungry customers.
+To keep things moving, each customer takes a numbered ticket when they arrive.
+
+When it’s time to call the next person, Yaʻqūb reads their number out loud, always in full English words to make sure everyone hears it clearly.

exercises/practice/simple-cipher/.docs/instructions.md

@@ -1,66 +1,40 @@
 # Instructions
 
-Implement a simple shift cipher like Caesar and a more secure substitution cipher.
+Create an implementation of the [Vigenère cipher][wiki].
+The Vigenère cipher is a simple substitution cipher.
 
-## Step 1
+## Cipher terminology
 
-"If he had anything confidential to say, he wrote it in cipher, that is, by so changing the order of the letters of the alphabet, that not a word could be made out.
-If anyone wishes to decipher these, and get at their meaning, he must substitute the fourth letter of the alphabet, namely D, for A, and so with the others."
-—Suetonius, Life of Julius Caesar
+A cipher is an algorithm used to encrypt, or encode, a string.
+The unencrypted string is called the _plaintext_ and the encrypted string is called the _ciphertext_.
+Converting plaintext to ciphertext is called _encoding_ while the reverse is called _decoding_.
 
-Ciphers are very straight-forward algorithms that allow us to render text less readable while still allowing easy deciphering.
-They are vulnerable to many forms of cryptanalysis, but Caesar was lucky that his enemies were not cryptanalysts.
+In a _substitution cipher_, each plaintext letter is replaced with a ciphertext letter which is computed with the help of a _key_.
+(Note, it is possible for replacement letter to be the same as the original letter.)
 
-The Caesar cipher was used for some messages from Julius Caesar that were sent afield.
-Now Caesar knew that the cipher wasn't very good, but he had one ally in that respect: almost nobody could read well.
-So even being a couple letters off was sufficient so that people couldn't recognize the few words that they did know.
+## Encoding details
 
-Your task is to create a simple shift cipher like the Caesar cipher.
-This image is a great example of the Caesar cipher:
+In this cipher, the key is a series of lowercase letters, such as `"abcd"`.
+Each letter of the plaintext is _shifted_ or _rotated_ by a distance based on a corresponding letter in the key.
+An `"a"` in the key means a shift of 0 (that is, no shift).
+A `"b"` in the key means a shift of 1.
+A `"c"` in the key means a shift of 2, and so on.
 
-![Caesar cipher][img-caesar-cipher]
+The first letter of the plaintext uses the first letter of the key, the second letter of the plaintext uses the second letter of the key and so on.
+If you run out of letters in the key before you run out of letters in the plaintext, start over from the start of the key again.
 
-For example:
+If the key only contains one letter, such as `"dddddd"`, then all letters of the plaintext are shifted by the same amount (three in this example), which would make this the same as a rotational cipher or shift cipher (sometimes called a Caesar cipher).
+For example, the plaintext `"iamapandabear"` would become `"ldpdsdqgdehdu"`.
 
-Giving "iamapandabear" as input to the encode function returns the cipher "ldpdsdqgdehdu".
-Obscure enough to keep our message secret in transit.
+If the key only contains the letter `"a"` (one or more times), the shift distance is zero and the ciphertext is the same as the plaintext.
 
-When "ldpdsdqgdehdu" is put into the decode function it would return the original "iamapandabear" letting your friend read your original message.
+Usually the key is more complicated than that, though!
+If the key is `"abcd"` then letters of the plaintext would be shifted by a distance of 0, 1, 2, and 3.
+If the plaintext is `"hello"`, we need 5 shifts so the key would wrap around, giving shift distances of 0, 1, 2, 3, and 0.
+Applying those shifts to the letters of `"hello"` we get `"hfnoo"`.
 
-## Step 2
+## Random keys
 
-Shift ciphers quickly cease to be useful when the opposition commander figures them out.
-So instead, let's try using a substitution cipher.
-Try amending the code to allow us to specify a key and use that for the shift distance.
+If no key is provided, generate a key which consists of at least 100 random lowercase letters from the Latin alphabet.
 
-Here's an example:
-
-Given the key "aaaaaaaaaaaaaaaaaa", encoding the string "iamapandabear"
-would return the original "iamapandabear".
-
-Given the key "ddddddddddddddddd", encoding our string "iamapandabear"
-would return the obscured "ldpdsdqgdehdu"
-
-In the example above, we've set a = 0 for the key value.
-So when the plaintext is added to the key, we end up with the same message coming out.
-So "aaaa" is not an ideal key.
-But if we set the key to "dddd", we would get the same thing as the Caesar cipher.
-
-## Step 3
-
-The weakest link in any cipher is the human being.
-Let's make your substitution cipher a little more fault tolerant by providing a source of randomness and ensuring that the key contains only lowercase letters.
-
-If someone doesn't submit a key at all, generate a truly random key of at least 100 lowercase characters in length.
-
-## Extensions
-
-Shift ciphers work by making the text slightly odd, but are vulnerable to frequency analysis.
-Substitution ciphers help that, but are still very vulnerable when the key is short or if spaces are preserved.
-Later on you'll see one solution to this problem in the exercise "crypto-square".
-
-If you want to go farther in this field, the questions begin to be about how we can exchange keys in a secure way.
-Take a look at [Diffie-Hellman on Wikipedia][dh] for one of the first implementations of this scheme.
-
-[img-caesar-cipher]: https://upload.wikimedia.org/wikipedia/commons/thumb/4/4a/Caesar_cipher_left_shift_of_3.svg/320px-Caesar_cipher_left_shift_of_3.svg.png
-[dh]: https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange
+[wiki]: https://en.wikipedia.org/wiki/Vigen%C3%A8re_cipher

exercises/practice/simple-cipher/.meta/config.json

@@ -20,15 +20,15 @@
       ".meta/proof.ci.ts"
     ]
   },
-  "blurb": "Implement a simple shift cipher like Caesar and a more secure substitution cipher.",
+  "blurb": "Implement the Vigenère cipher, a simple substitution cipher.",
   "custom": {
     "version.tests.compatibility": "jest-29",
     "flag.tests.task-per-describe": false,
     "flag.tests.may-run-long": false,
     "flag.tests.includes-optional": false,
     "flag.tests.jest": true,
     "flag.tests.tstyche": false
-  },
+  }
   "source": "Substitution Cipher at Wikipedia",
   "source_url": "https://en.wikipedia.org/wiki/Substitution_cipher"
 }

exercises/practice/triangle/.docs/instructions.md

@@ -13,6 +13,12 @@ A _scalene_ triangle has all sides of different lengths.
 
 For a shape to be a triangle at all, all sides have to be of length > 0, and the sum of the lengths of any two sides must be greater than or equal to the length of the third side.
 
+~~~~exercism/note
+_Degenerate triangles_ are triangles where the sum of the length of two sides is **equal** to the length of the third side, e.g. `1, 1, 2`.
+We opted to not include tests for degenerate triangles in this exercise.
+You may handle those situations if you wish to do so, or safely ignore them.
+~~~~
+
 In equations:
 
 Let `a`, `b`, and `c` be sides of the triangle.