Preserve main routes and registry data after rebase

Author: adewale

docs/quality-registries.toml

@@ -794,6 +794,11 @@ kind = "example"
 value = "iterating-over-iterables"
 description = "separate value producers from value consumers"
 
+[[journeys.sections.items]]
+kind = "example"
+value = "iterator-vs-iterable"
+description = "distinguish re-iterable collections from one-pass iterators"
+
 [[journeys.sections.items]]
 kind = "example"
 value = "iterators"
@@ -1012,6 +1017,11 @@ kind = "example"
 value = "properties"
 description = "keep attribute syntax while adding computation or validation"
 
+[[journeys.sections.items]]
+kind = "example"
+value = "classmethods-and-staticmethods"
+description = "choose between instance, class, and static behavior on a class"
+
 [[journeys.sections.items]]
 kind = "example"
 value = "special-methods"
@@ -1042,6 +1052,11 @@ kind = "example"
 value = "attribute-access"
 description = "customize fallback lookup and assignment carefully"
 
+[[journeys.sections.items]]
+kind = "example"
+value = "bound-and-unbound-methods"
+description = "explain how attribute access turns a function into a bound method"
+
 [[journeys.sections.items]]
 kind = "example"
 value = "descriptors"
@@ -1071,6 +1086,11 @@ kind = "example"
 value = "protocols"
 description = "describe required behavior by structural shape"
 
+[[journeys.sections.items]]
+kind = "example"
+value = "abstract-base-classes"
+description = "contrast runtime-enforced nominal interfaces with structural protocols"
+
 [[journeys.sections.items]]
 kind = "example"
 value = "enums"
@@ -1100,6 +1120,11 @@ kind = "example"
 value = "typed-dicts"
 description = "type dictionary records that come from JSON"
 
+[[journeys.sections.items]]
+kind = "example"
+value = "structured-data-shapes"
+description = "choose between dataclass, NamedTuple, and TypedDict for records"
+
 [[journeys.sections.items]]
 kind = "example"
 value = "literal-and-final"
@@ -1334,6 +1359,12 @@ anchor = "cell-0"
 figure = "aliasing-mutation"
 caption = "Two names share one mutable list — appending through one name changes the object visible through both."
 
+[[figure_attachments]]
+slug = "mutability"
+anchor = "cell-0"
+figure = "tuple-no-mutation"
+caption = "By contrast, a tuple is frozen — its contents cannot change in place, so aliasing carries no mutation hazard."
+
 [[figure_attachments]]
 slug = "variables"
 anchor = "cell-0"
@@ -1466,6 +1497,12 @@ anchor = "cell-0"
 figure = "positional-only-separator"
 caption = "A bare `/` divides positional-only arguments from positional-or-keyword ones; callers cannot name `a` or `b`."
 
+[[figure_attachments]]
+slug = "positional-only-parameters"
+anchor = "cell-0"
+figure = "kw-only-separator"
+caption = "In the same signature, the bare `*` works the other way: parameters after it, such as `clamp`, must be named at the call site."
+
 [[figure_attachments]]
 slug = "closures"
 anchor = "cell-0"
@@ -1532,6 +1569,12 @@ anchor = "cell-0"
 figure = "iter-protocol"
 caption = "An iterable knows how to produce an iterator (via iter()); the iterator knows how to produce values (via next())."
 
+[[figure_attachments]]
+slug = "iterator-vs-iterable"
+anchor = "cell-1"
+figure = "iterator-unroll"
+caption = "The iterator's caret only moves forward — after the first `list(stream)` drains it, nothing is left for the second."
+
 [[figure_attachments]]
 slug = "type-aliases"
 anchor = "cell-0"
@@ -1658,6 +1701,12 @@ anchor = "cell-0"
 figure = "metaclass-triangle"
 caption = "A metaclass is the type of a class, just as a class is the type of its instances; type is the default metaclass."
 
+[[figure_attachments]]
+slug = "metaclasses"
+anchor = "cell-0"
+figure = "class-triangle"
+caption = "The class makes instances — the same triangle one level down, with type as the default apex."
+
 [[figure_attachments]]
 slug = "modules"
 anchor = "cell-0"
@@ -1732,10 +1781,16 @@ caption = "Sets are hash buckets without values; `x in s` averages O(1) regardle
 
 [[figure_attachments]]
 slug = "tuples"
-anchor = "cell-0"
+anchor = "cell-3"
 figure = "tuple-frozen"
 caption = "Tuples are ordered, immutable sequences; positions matter, contents do not change once constructed."
 
+[[figure_attachments]]
+slug = "tuples"
+anchor = "cell-3"
+figure = "list-append"
+caption = "A list is the other intent: a variable number of similar items, growing in place with `.append`."
+
 [[figure_attachments]]
 slug = "values"
 anchor = "cell-0"

public/prototyping/marginalia-gestalt.html

@@ -148,6 +148,13 @@ <h3>Mutability</h3>
   <p class="caption">Two names share one mutable list — appending through one name changes the object visible through both.</p>
   <p class="score score-high">9.5 · three-state small multiple of aliased mutation</p>
 </div>
+<div class="card">
+  <p class="eyebrow">Data Model · 12</p>
+  <h3>Mutability</h3>
+  <svg viewBox="-14 -14 248 213" width="397" height="341" aria-hidden="true" focusable="false" xmlns="http://www.w3.org/2000/svg"><text x="0" y="12" font-family="-apple-system, 'Source Sans Pro', sans-serif" font-size="8" fill="rgba(82, 16, 0, 0.7)" text-anchor="start" letter-spacing="0.5">TUPLE — FROZEN</text><rect x="0" y="18" width="60" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="30.0" y="34.0" font-family="'Iowan Old Style', Charter, Georgia, serif" font-size="11" fill="#521000" text-anchor="middle" font-style="italic">first</text><rect x="0" y="48" width="60" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="30.0" y="64.0" font-family="'Iowan Old Style', Charter, Georgia, serif" font-size="11" fill="#521000" text-anchor="middle" font-style="italic">second</text><line x1="60" y1="30" x2="80.03839178306819" y2="42.331318020349656" stroke="#521000" stroke-width="1.0"/><polygon points="86,46 78.57091899120806,44.71596130712238 81.50586457492832,39.946674733576934" fill="#521000"/><line x1="60" y1="60" x2="79.83670230054477" y2="49.31869876124512" stroke="#521000" stroke-width="1.0"/><polygon points="86,46 81.16418180504282,51.784017841027215 78.50922279604673,46.85337968146303" fill="#521000"/><rect x="88" y="32" width="110" height="28" fill="rgba(82, 16, 0, 0.05)" stroke="#521000" stroke-width="1.0"/><text x="143.0" y="50.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">("python",)</text><text x="0" y="102" font-family="-apple-system, 'Source Sans Pro', sans-serif" font-size="8" fill="rgba(82, 16, 0, 0.7)" text-anchor="start" letter-spacing="0.5">NO .APPEND</text><rect x="0" y="108" width="60" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="30.0" y="124.0" font-family="'Iowan Old Style', Charter, Georgia, serif" font-size="11" fill="#521000" text-anchor="middle" font-style="italic">first</text><rect x="0" y="138" width="60" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="30.0" y="154.0" font-family="'Iowan Old Style', Charter, Georgia, serif" font-size="11" fill="#521000" text-anchor="middle" font-style="italic">second</text><line x1="60" y1="120" x2="80.03839178306819" y2="132.33131802034967" stroke="#521000" stroke-width="1.0"/><polygon points="86,136 78.57091899120806,134.7159613071224 81.50586457492832,129.94667473357694" fill="#521000"/><line x1="60" y1="150" x2="79.83670230054477" y2="139.31869876124512" stroke="#521000" stroke-width="1.0"/><polygon points="86,136 81.16418180504282,141.7840178410272 78.50922279604673,136.85337968146303" fill="#521000"/><rect x="88" y="122" width="110" height="28" fill="rgba(82, 16, 0, 0.05)" stroke="#521000" stroke-width="1.0"/><text x="143.0" y="140.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">("python",)</text><text x="150" y="170" font-family="-apple-system, 'Source Sans Pro', sans-serif" font-size="9" fill="rgba(82, 16, 0, 0.7)" text-anchor="middle">tuples raise AttributeError</text></svg>
+  <p class="caption">By contrast, a tuple is frozen — its contents cannot change in place, so aliasing carries no mutation hazard.</p>
+  <p class="score score-high">9.5 · three-state small multiple of aliased mutation</p>
+</div>
 <div class="card">
   <p class="eyebrow">Basics · 13</p>
   <h3>Object Lifecycle</h3>
@@ -239,6 +246,13 @@ <h3>Iterator vs Iterable</h3>
   <p class="caption">An iterable knows how to produce an iterator (via iter()); the iterator knows how to produce values (via next()).</p>
   <p class="score score-high">9.0 · the protocol exposed</p>
 </div>
+<div class="card">
+  <p class="eyebrow">Iteration · 25</p>
+  <h3>Iterator vs Iterable</h3>
+  <svg viewBox="-14 -14 248 158" width="397" height="253" aria-hidden="true" focusable="false" xmlns="http://www.w3.org/2000/svg"><rect x="20" y="8" width="24" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="32.0" y="24.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">a</text><rect x="44" y="8" width="24" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="56.0" y="24.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">b</text><rect x="68" y="8" width="24" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="80.0" y="24.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">c</text><rect x="92" y="8" width="24" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="104.0" y="24.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">d</text><polygon points="32,7 28,1 36,1" fill="#521000"/><text x="124" y="24" font-family="-apple-system, 'Source Sans Pro', sans-serif" font-size="9" fill="rgba(82, 16, 0, 0.7)" text-anchor="start">next()</text><rect x="20" y="38" width="24" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="32.0" y="54.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">a</text><rect x="44" y="38" width="24" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="56.0" y="54.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">b</text><rect x="68" y="38" width="24" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="80.0" y="54.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">c</text><rect x="92" y="38" width="24" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="104.0" y="54.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">d</text><polygon points="56,37 52,31 60,31" fill="#521000"/><text x="124" y="54" font-family="-apple-system, 'Source Sans Pro', sans-serif" font-size="9" fill="rgba(82, 16, 0, 0.7)" text-anchor="start">next()</text><rect x="20" y="68" width="24" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="32.0" y="84.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">a</text><rect x="44" y="68" width="24" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="56.0" y="84.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">b</text><rect x="68" y="68" width="24" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="80.0" y="84.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">c</text><rect x="92" y="68" width="24" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="104.0" y="84.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">d</text><polygon points="80,67 76,61 84,61" fill="#521000"/><text x="124" y="84" font-family="-apple-system, 'Source Sans Pro', sans-serif" font-size="9" fill="rgba(82, 16, 0, 0.7)" text-anchor="start">next()</text><rect x="20" y="98" width="24" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="32.0" y="114.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">a</text><rect x="44" y="98" width="24" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="56.0" y="114.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">b</text><rect x="68" y="98" width="24" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="80.0" y="114.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">c</text><rect x="92" y="98" width="24" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="104.0" y="114.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">d</text><polygon points="104,97 100,91 108,91" fill="#FF4801"/><text x="124" y="114" font-family="-apple-system, 'Source Sans Pro', sans-serif" font-size="9" fill="rgba(82, 16, 0, 0.7)" text-anchor="start">next() — last</text></svg>
+  <p class="caption">The iterator's caret only moves forward — after the first `list(stream)` drains it, nothing is left for the second.</p>
+  <p class="score score-high">9.0 · the protocol exposed</p>
+</div>
 <div class="card">
   <p class="eyebrow">Iteration · 26</p>
   <h3>Sentinel Iteration</h3>
@@ -288,6 +302,13 @@ <h3>Tuples</h3>
   <p class="caption">Tuples are ordered, immutable sequences; positions matter, contents do not change once constructed.</p>
   <p class="score score-high">9.0 · frozen sequence with struck-through .append</p>
 </div>
+<div class="card">
+  <p class="eyebrow">Collections · 31</p>
+  <h3>Tuples</h3>
+  <svg viewBox="-14 -14 248 64" width="397" height="102" aria-hidden="true" focusable="false" xmlns="http://www.w3.org/2000/svg"><rect x="0" y="8" width="24" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="12.0" y="24.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">3</text><rect x="24" y="8" width="24" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="36.0" y="24.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">1</text><rect x="48" y="8" width="24" height="24" fill="none" stroke="#521000" stroke-width="1.0"/><text x="60.0" y="24.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">4</text><rect x="72" y="8" width="24" height="24" fill="none" stroke="#521000" stroke-width="0.5" opacity="0.4"/><text x="84.0" y="24.0" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">+1</text><line x1="98" y1="20" x2="125.0" y2="20.0" stroke="#FF4801" stroke-width="1.4"/><polygon points="132,20 125.0,22.8 125.0,17.2" fill="#FF4801"/><text x="136" y="18" font-family="-apple-system, 'Source Sans Pro', sans-serif" font-size="9" fill="rgba(82, 16, 0, 0.7)" text-anchor="start">.append</text></svg>
+  <p class="caption">A list is the other intent: a variable number of similar items, growing in place with `.append`.</p>
+  <p class="score score-high">9.0 · frozen sequence with struck-through .append</p>
+</div>
 <div class="card">
   <p class="eyebrow">Collections · 32</p>
   <h3>Unpacking</h3>
@@ -372,6 +393,13 @@ <h3>Positional-only Parameters</h3>
   <p class="caption">A bare `/` divides positional-only arguments from positional-or-keyword ones; callers cannot name `a` or `b`.</p>
   <p class="score score-high">9.0 · signature with explicit `/` separator</p>
 </div>
+<div class="card">
+  <p class="eyebrow">Functions · 43</p>
+  <h3>Positional-only Parameters</h3>
+  <svg viewBox="-14 -14 228 84" width="365" height="134" aria-hidden="true" focusable="false" xmlns="http://www.w3.org/2000/svg"><text x="0" y="18" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="start">def f(a, b, *, c, d): …</text><line x1="75.0" y1="22" x2="75.0" y2="38" stroke="#521000" stroke-width="0.6" stroke-dasharray="2 2"/><text x="33" y="50" font-family="-apple-system, 'Source Sans Pro', sans-serif" font-size="9" fill="rgba(82, 16, 0, 0.7)" text-anchor="middle">positional or kw</text><text x="120" y="50" font-family="-apple-system, 'Source Sans Pro', sans-serif" font-size="9" fill="rgba(82, 16, 0, 0.7)" text-anchor="middle">keyword only</text></svg>
+  <p class="caption">In the same signature, the bare `*` works the other way: parameters after it, such as `clamp`, must be named at the call site.</p>
+  <p class="score score-high">9.0 · signature with explicit `/` separator</p>
+</div>
 <div class="card">
   <p class="eyebrow">Functions · 44</p>
   <h3>Args and Kwargs</h3>
@@ -554,6 +582,13 @@ <h3>Metaclasses</h3>
   <p class="caption">A metaclass is the type of a class, just as a class is the type of its instances; type is the default metaclass.</p>
   <p class="score score-high">9.0 · extended triangle to metaclass</p>
 </div>
+<div class="card">
+  <p class="eyebrow">Classes · 69</p>
+  <h3>Metaclasses</h3>
+  <svg viewBox="-14 -14 302 88" width="483" height="141" aria-hidden="true" focusable="false" xmlns="http://www.w3.org/2000/svg"><circle cx="20" cy="28" r="2.5" fill="#521000"/><text x="20" y="54" font-family="-apple-system, 'Source Sans Pro', sans-serif" font-size="9" fill="rgba(82, 16, 0, 0.7)" text-anchor="middle">instance</text><line x1="26" y1="28" x2="79.0" y2="28.0" stroke="#521000" stroke-width="1.0"/><polygon points="86,28 79.0,30.8 79.0,25.2" fill="#521000"/><rect x="88" y="10" width="60" height="36" fill="none" stroke="#521000" stroke-width="1.0"/><text x="94" y="7" font-family="-apple-system, 'Source Sans Pro', sans-serif" font-size="8" fill="rgba(82, 16, 0, 0.7)" text-anchor="start" letter-spacing="0.5">CLASS</text><text x="118" y="32" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">Class</text><line x1="148" y1="28" x2="201.0" y2="28.0" stroke="#521000" stroke-width="1.0"/><polygon points="208,28 201.0,30.8 201.0,25.2" fill="#521000"/><rect x="210" y="10" width="60" height="36" fill="none" stroke="#521000" stroke-width="1.0"/><text x="216" y="7" font-family="-apple-system, 'Source Sans Pro', sans-serif" font-size="8" fill="rgba(82, 16, 0, 0.7)" text-anchor="start" letter-spacing="0.5">TYPE</text><text x="240.0" y="32" font-family="'JetBrains Mono', 'IBM Plex Mono', Menlo, monospace" font-size="10" fill="#521000" text-anchor="middle">type</text></svg>
+  <p class="caption">The class makes instances — the same triangle one level down, with type as the default apex.</p>
+  <p class="score score-high">9.0 · extended triangle to metaclass</p>
+</div>
 <div class="card">
   <p class="eyebrow">Data Model · 70</p>
   <h3>Context Managers</h3>