docs: add linked tables of contents to the guide pages

- Every guide page gets a "Contents:" block of anchor links after the
  intro, and ai-reference's existing list is now clickable
- Also added to the two long internal pages; skipped the README, the
  docs index, changelog/upgrade notes, and the generated behavior matrix

Based on Lucia's doc-review branch, regenerated against current headings.

Author: daveedis

docs/ai-reference.md

@@ -16,24 +16,24 @@ links here are absolute).
 
 Contents:
 
-- What is SmartArray
-- Class Hierarchy and Type Hints
-- Creating Collections
-- Reading and Writing Fields
-- Missing Keys and SmartNull
-- Iteration and Keys
-- Mode Conversion and Plain Arrays
-- Single Elements - first(), last(), at()
-- Collection Checks - count(), isEmpty(), isNotEmpty(), contains()
-- Row Position - isFirst(), isLast(), position()
-- Filtering and Sorting - where(), whereNot(), whereInList(), filter(), sort(), sortBy(), unique()
-- Transforming and Grouping - column(), columnAt(), indexBy(), groupBy(), keys(), values(), map(), merge(), implode()
-- Guards - or404(), orDie(), orThrow(), orRedirect()
-- Database Metadata - mysqli(), load()
-- Debugging - debug()
-- Errors and Exceptions
-- Deprecated Names
-- Gotchas Quick Reference
+- [What is SmartArray](#what-is-smartarray)
+- [Class Hierarchy and Type Hints](#class-hierarchy-and-type-hints)
+- [Creating Collections](#creating-collections)
+- [Reading and Writing Fields](#reading-and-writing-fields)
+- [Missing Keys and SmartNull](#missing-keys-and-smartnull)
+- [Iteration and Keys](#iteration-and-keys)
+- [Mode Conversion and Plain Arrays](#mode-conversion-and-plain-arrays)
+- [Single Elements](#single-elements) - first(), last(), at()
+- [Collection Checks](#collection-checks) - count(), isEmpty(), isNotEmpty(), contains()
+- [Row Position](#row-position) - isFirst(), isLast(), position()
+- [Filtering and Sorting](#filtering-and-sorting) - where(), whereNot(), whereInList(), filter(), sort(), sortBy(), unique()
+- [Transforming and Grouping](#transforming-and-grouping) - column(), columnAt(), indexBy(), groupBy(), keys(), values(), map(), merge(), implode()
+- [Guards](#guards) - or404(), orDie(), orThrow(), orRedirect()
+- [Database Metadata](#database-metadata) - mysqli(), load()
+- [Debugging](#debugging) - debug()
+- [Errors and Exceptions](#errors-and-exceptions)
+- [Deprecated Names](#deprecated-names)
+- [Gotchas Quick Reference](#gotchas-quick-reference)
 
 ---
 

docs/common-patterns.md

@@ -5,6 +5,15 @@ built from methods covered on earlier pages, and the examples assume
 database rows from [ZenDB](https://github.com/interactivetools-com/ZenDB)
 or `SmartArrayHtml::new($records)`.
 
+Contents:
+
+- [Showing Related Names Without a Join](#showing-related-names-without-a-join)
+- [Select Dropdowns from Query Results](#select-dropdowns-from-query-results)
+- [Top N with a "More" Link](#top-n-with-a-more-link)
+- [Grouped Headings with Counts](#grouped-headings-with-counts)
+- [Safe Id Lists for SQL IN Clauses](#safe-id-lists-for-sql-in-clauses)
+- [Results with Unpredictable Column Names](#results-with-unpredictable-column-names)
+
 ## Showing Related Names Without a Join
 
 When rows reference another table by id, one keyed map replaces the join:

docs/displaying-fields.md

@@ -6,6 +6,16 @@ How to show fields in templates and handle data that isn't there: fallbacks
 for blank values, "no results" messages, and required records that stop the
 page.
 
+Contents:
+
+- [Reading Fields](#reading-fields)
+- [Fallbacks with or()](#fallbacks-with-or)
+- [Showing a "No Results" Message](#showing-a-no-results-message)
+- [When Data Is Missing](#when-data-is-missing)
+- [Requiring Data: The Guards](#requiring-data-the-guards)
+- [Checking a Single Field](#checking-a-single-field)
+- [Keys Property Syntax Can't Type](#keys-property-syntax-cant-type)
+
 ## Reading Fields
 
 A SmartArray is an object, not an array, so you read fields with the arrow

docs/filtering-and-sorting.md

@@ -3,6 +3,15 @@
 How to narrow a loaded result down to the rows you want and put them in the
 right order: matching, excluding, custom tests, sorting, and duplicates.
 
+Contents:
+
+- [Matching Rows: where()](#matching-rows-where)
+- [Excluding Rows: whereNot()](#excluding-rows-wherenot)
+- [CMS Builder List Fields: whereInList()](#cms-builder-list-fields-whereinlist)
+- [Custom Tests: filter()](#custom-tests-filter)
+- [Sorting: sortBy() and sort()](#sorting-sortby-and-sort)
+- [Duplicates and Membership: unique() and contains()](#duplicates-and-membership-unique-and-contains)
+
 ## Matching Rows: where()
 
 Choosing which rows to load is the query's job (SQL's WHERE clause);

docs/getting-started.md

@@ -7,6 +7,15 @@ methods, with fields that HTML-encode themselves on output. This page covers
 installation, your first collection, the mental model behind the two classes,
 and the everyday basics: loops, field access, and debugging.
 
+Contents:
+
+- [Installation](#installation)
+- [Your First SmartArray](#your-first-smartarray)
+- [The Mental Model](#the-mental-model)
+- [Working with ZenDB and CMS Builder](#working-with-zendb-and-cms-builder)
+- [Converting to Plain Arrays](#converting-to-plain-arrays)
+- [Debugging](#debugging)
+
 ## Installation
 
 Using CMS Builder or [ZenDB](https://github.com/interactivetools-com/ZenDB)?

docs/method-reference.md

@@ -3,6 +3,20 @@
 Every method, grouped by what it returns. Each group heading links to the
 guide page that teaches those methods.
 
+Contents:
+
+- [Basic Usage](#basic-usage)
+- [Creation and Conversion](#creation-and-conversion)
+- [Single Elements](#single-elements)
+- [Writing Values](#writing-values)
+- [Collection Checks](#collection-checks)
+- [Row Position](#row-position)
+- [Filtering and Sorting](#filtering-and-sorting)
+- [Transforming and Grouping](#transforming-and-grouping)
+- [Requiring Results](#requiring-results)
+- [Database Metadata](#database-metadata)
+- [Debugging](#debugging)
+
 ### [Basic Usage](getting-started.md)
 
 ```php

docs/outputting-html.md

@@ -6,6 +6,14 @@ The first two pages used auto-encoding without explaining it. This page
 covers how it works, how to output trusted HTML like WYSIWYG editor content, and
 the row helpers that control loop layout.
 
+Contents:
+
+- [How Auto-Encoding Works](#how-auto-encoding-works)
+- [Where Encoding Ends](#where-encoding-ends)
+- [Trusted HTML: rawHtml()](#trusted-html-rawhtml)
+- [Loop Layout: isFirst(), isLast(), position()](#loop-layout-isfirst-islast-position)
+- [Keys Are Never Encoded](#keys-are-never-encoded)
+
 ## How Auto-Encoding Works
 
 A field holds your original value, exactly as it came from the database,

docs/performance.md

@@ -17,6 +17,13 @@ cost hundreds of times more.
 The rest of this page is the measurements behind those claims, and the one
 case where the overhead is worth thinking about.
 
+Contents:
+
+- [What a Page Costs](#what-a-page-costs)
+- [Memory](#memory)
+- [When to Care](#when-to-care)
+- [Reproducing the Numbers](#reproducing-the-numbers)
+
 ## What a Page Costs
 
 A news site with 25 records (60-char title, 300-char summary, 5KB content),

docs/transforming-and-grouping.md

@@ -3,6 +3,15 @@
 How to reshape a loaded result: pull one column out, key rows for instant
 lookups, group them for section headings, and rebuild rows into new shapes.
 
+Contents:
+
+- [Pulling One Column: column()](#pulling-one-column-column)
+- [Keying Rows for Lookups: indexBy()](#keying-rows-for-lookups-indexby)
+- [Using Fields as Lookup Keys](#using-fields-as-lookup-keys)
+- [Grouping Rows: groupBy()](#grouping-rows-groupby)
+- [Reshaping Rows: map()](#reshaping-rows-map)
+- [Keys and Values](#keys-and-values)
+
 ## Pulling One Column: column()
 
 Use `column()` to get a flat list of one field from every row (like PHP's

docs/troubleshooting.md

@@ -6,6 +6,16 @@ Common error messages and how to fix them, plus the gotchas that don't
 produce an error at all. Headings quote the message or symptom so you can
 find them by search.
 
+Contents:
+
+- [empty() and if() checks on fields don't work as expected](#empty-and-if-checks-on-fields-dont-work-as-expected)
+- [A === null check never matches](#a--null-check-never-matches)
+- [Warning: Can't convert SmartArrayHtml to string](#warning-cant-convert-smartarrayhtml-to-string)
+- [Warning: some_field is undefined in listings.php:12](#warning-some_field-is-undefined-in-listingsphp12)
+- [Casting with (array) returns internal object data](#casting-with-array-returns-internal-object-data)
+- [json_encode() returns an object instead of an array](#json_encode-returns-an-object-instead-of-an-array)
+- [A lookup using a field as the key renders blank](#a-lookup-using-a-field-as-the-key-renders-blank)
+
 ### empty() and if() checks on fields don't work as expected
 
 In HTML mode a field is an object wrapping your value, and PHP's `empty()`