Docs rewrite: every snippet runs, every fact matches the code, and the API reference renders cleanly #698

Problem Statement

A developer reads Ferro's quickstart, copies the "Filtering with where()" block into a script, and runs it:

        adults = await User.where(lambda user: user.age >= 18).all()
IndentationError: unexpected indent

They remove the indentation and run it again:

RuntimeError: No database route

Since 0.13 every ORM call has to run inside async with engines.session():. Every embedded snippet starts inside that block, so no page shows it. The SQLAlchemy migration page goes further and tells the reader there is "no session to manage".

A full audit of the site against the writing-for-humans rules and the repo's invariants (I-7, I-8, I-11) found this pattern everywhere. It covered 51 pages, 46 example scripts and 334 public docstrings, and graded 21 of the 51 pages C (substantial rework). It counted about 100 serious findings (wrong facts, broken examples, invariant breaches), 300 rule breaches a reader would notice, and 240 polish items.

Wrong facts on the pages people read first:

• The field type table says str becomes TEXT; Ferro creates varchar. The same page's own DDL contradicts the table.
• The upgrade guide stops at 0.15 although the package is at 0.25.0, and one of its recipes subclasses a Ferro class that doesn't exist.
• The FAQ says Ferro has no eager loading, but include() ships.
• The front page says Pydantic is the only dependency; pydantic-settings is required too.
• The contributing guide gives the wrong license and links to a GitHub Discussions page that is turned off.

Recipes that teach the wrong thing:

• The Pagination how-to builds keyset paging by hand and never mentions Query.after() / .before().
• On SQLite, the Timestamps how-to's update(...) recipe writes a different datetime format from save(), which is the exact bug I-13 exists to prevent.
• The schema guide says auto-migrate ignores a rename hint, contradicting the rest of the section.

An API reference that shows markup and internals instead of the API:

• About 280 Sphinx roles render as literal text, for example ":class: ~ferro.checks.Check".
• About 180 members with no docstring, the dunder methods and the internal __ferro_*__ registry attributes all appear, alongside 191 source blocks.
• ferro.migrate's Returns: section renders as five broken table rows.
• The FerroField option table is silently dropped.
• Five public objects (FieldProxy, QueryNode, RelationProxy, ValueExpr, ModelConnection) have no entry.

Pages that hide the answer:

• About 50 snippet sections end just above the assert that holds the result, so the reader sees a query but never what it returns.
• Most guide pages switch between 3 and 14 unrelated models.
• No query example shows the SQL it produces.
• About 200 headings are in Title Case or phrased as slogans.
• User-facing pages cite about 100 ADR numbers, issue numbers and internal codenames the reader cannot follow.

A CLI whose help text loses words: ferro migrate rerecord --help prints "The step whose edit to accept: :, as 0007:01". The <migration>:<step> placeholders are swallowed as markup.

An invariant that no longer matches the code: AGENTS.md I-8 still orders predicate styles as "lambda > col() > operator" and calls operator style "compatible today". Both col() and operator predicates were removed in 0.14, and where() now rejects anything that isn't a callable. The part of I-8 that does still apply, naming the lambda parameter after the model, is broken about 160 times (lambda t:), and the Queries guide teaches "t by convention".

These defects got through because nothing catches them:

• 184 inline code blocks are compile-checked and never run.
• 12 error checks in the examples assert only inside except, so they pass when the error stops being raised.
• Quoted generated migration files are not compared with what the generator writes.
• The site build is not strict.
• No test looks at the rendered pages.

Solution

A developer can copy any block from any page and run it. Each page opens by saying what it is, keeps one set of models from top to bottom, and shows what every call returns, with the SQL beside the query. When the reader picks the Annotated tab once, every tab pair on the site follows. The API reference shows the public API, with linked types, parameter tables and one-line summaries in one consistent form. A reader who meets "RLS" or "DDL" can hover over it for the definition. Old URLs redirect to their new location.

Three test seams keep it that way:

1. The built site. One test builds the site the way CI does (strict, so a warning fails the build). It then checks the rendered HTML for the defect classes this audit found:

   • literal Sphinx roles
   • Returns: sections split into broken rows
   • Attributes: / Args: sections griffe dropped
   • snippet code that keeps its leading indentation
   • public exports with no API entry

   This catches docstring and config regressions together, because both end up on the rendered page.

2. The docs examples harness, extended.

   • Inline page blocks that do real work run, or move into examples that run.
   • Each lambda passed to a query method takes a parameter named after its model.
   • An error check fails when the error it expects is not raised.
   • Docstring examples run against a shared running example.

3. The migrations docs harness, extended. Every quoted generated step file is compared with a fresh generation, and every ferro … --help text quoted on a page keeps its placeholders.

Prose rules that no test can check, such as page kind, lead-in and result sentences, headings and minimising words, are checked in review against writing-for-humans.

The site tooling moves to what Zensical 0.0.71, pymdown-extensions 12.3 and mkdocstrings-python 2.0.9 offer. On this branch the docs dependencies are already raised to those versions and relocked, and the site builds with one warning, which this work removes.

User Stories

Copying and running code

1. As a new user, I want every embedded snippet to render without leading indentation, so that pasting it into a file doesn't raise IndentationError.
2. As a new user, I want the first code block on each page to show the engines.session() wrapper, so that my copy runs instead of raising No database route.
3. As a new user, I want every page that shows a fragment to say where it runs and link to Connections › Sessions, so that I know which code surrounds it.
4. As a reader of any page, I want every code block I can copy to have been executed by the test suite, so that I can trust it runs as shown.
5. As a reader of the testing how-to, I want the fixtures it tells me to copy to be run by the test suite, so that my test setup works the first time.
6. As a maintainer, I want an example that claims "this raises" to fail its test when the error is no longer raised, so that the documented limits stay true.
7. As a reader of the schema guide, I want every generated migration file quoted on a page to match what ferro migrate new writes today, so that what I review in my repo matches the docs.
8. As a CLI user, I want ferro migrate <command> --help to print its <name>, <model>, <table>.<column> and <migration>:<step> placeholders, so that I can read the argument formats.

Correct facts

9. As a reader choosing column types, I want the field type table to show the type Ferro actually creates on each database, so that I can predict my schema.
10. As a maintainer, I want the field type table built from the same storage resolution the emitters use (I-1 item 3), so that it cannot drift from the DDL.
11. As a reader evaluating Ferro, I want the front page, Why Ferro and the FAQ to state the real dependencies, the real migration system and the real feature set, including include() and atomic updates, so that I judge Ferro on facts.
12. As a user upgrading Ferro, I want the upgrade guide to cover every release up to the current one, so that I know what each upgrade asks of me.
13. As a user upgrading Ferro, I want every upgrade recipe to use real classes and to show both declaration styles, so that I can apply it.
14. As a reader of the connections, mutations and performance pages, I want the identity map described as per-session, so that I understand when two loads return the same object.
15. As a Postgres user, I want the backends page to say JSON fields are stored as jsonb and to list the time type, so that I can index and query them correctly.
16. As a contributor, I want the contributing guide to state the actual license and link only to channels that exist, so that I contribute in the right place under the right terms.
17. As a CLI user, I want the CLI reference to list every flag the CLI accepts, including ferro migrate up --allow-ahead, so that the reference is complete.
18. As a reader of the schema guide, I want every page to describe rename hints the same way auto-migrate actually handles them, so that I am not surprised by a held-back table.
19. As a reader of the raw SQL guide, I want examples to query the table names Ferro creates (user, not users), so that my queries hit real tables.
20. As a reader of the relationships guide, I want the NO ACTION row to say the constraint is enforced, so that I choose delete behaviour correctly.
21. As a reader of the transactions guide, I want to be told that a rollback leaves my Python objects modified, so that I reload them before reusing them.
22. As a reader of the model and field docstrings, I want nullable described as the NOT NULL it sets in every emitter, so that I don't think it only affects Alembic.

Recipes that teach the right approach

23. As a developer paging results, I want the Pagination how-to built on Query.after() and .before(), so that I use the cursor paging Ferro ships instead of hand-rolling it.
24. As a developer exposing paged results over HTTP, I want the API endpoint example to open a session and run, so that I can start from it.
25. As a developer adding timestamps, I want the Timestamps recipe to write datetimes the same way save() does, so that ordering, precision and timezone survive on SQLite.
26. As a developer sharing fields across models, I want one page to explain what happens when a Model base class declares fields, so that I learn the one true side effect (the base gets a table of its own) rather than three conflicting reasons.
27. As a developer writing tests, I want the testing how-to to catch UniqueViolationError rather than Exception, so that my tests check the error I mean.

Reading a page

28. As a reader, I want each page to be one kind (tutorial, how-to, reference or explanation), so that I find the facts I came for without wading through other material.
29. As a reader, I want each page to open with one sentence saying what it covers, then an example on the first screen, so that I can tell at once whether the page answers my question.
30. As a reader, I want each page to use one running example, introduced once, so that each new section shows only what changed.
31. As a reader, I want every code block introduced by a sentence ending in a colon and followed by a sentence on what changed, so that I know what to look at.
32. As a reader, I want to see what each query returns, as printed output or as the asserted value, so that I can check my understanding.
33. As a reader coming from SQL, I want the generated SQL shown beside each query and each schema feature, so that the ORM call becomes concrete.
34. As a reader, I want example data that reads like real records, has about four rows and has no tied values, so that I can verify results by eye.
35. As a reader scanning a page, I want headings that are short sentence-case noun phrases naming the feature, often with the API name in code, so that I find sections and link text makes sense.
36. As a reader, I want how-to titles to name the goal ("Paginate query results"), so that the page title tells me what it gives.
37. As a reader, I want sections ordered from the common case to the specialised one and ending with a link to the reference, so that I can stop once my case is covered.
38. As a reader, I want no words that minimise difficulty ("simply", "easy", "trivial"), so that I'm not made to feel slow when something is hard.
39. As a reader, I want admonitions used sparingly, each kind for one job, so that warnings stand out when they matter.
40. As a reader, I want version markers ("Added in 0.18") as self-contained blocks at the bottom of a section, and no dated or release-bound notes in the body, so that pages don't go stale when the next release ships.
41. As a reader, I want pages and docstrings free of ADR numbers, issue numbers, codenames and contributor-only references, so that every reference I see is one I can follow.
42. As a reader of the guide, I want option tables, exit codes, the auto-migrate matrix and the door comparison to live once in the reference and be linked from guides, so that the copies can't disagree.
43. As a reader of the row-level security page, I want explanation, setup steps and reference split apart, and a scoped query shown next to an unscoped one, so that I see what RLS does to my results.
44. As a reader of the migrations guide, I want squash on its own page and the tutorial loop on another, so that each page has one job.
45. As a reader, I want every lambda in the docs to name its parameter after the model (lambda user: user.age), so that the predicate reads like the sentence it means (I-8).

Navigating the site

46. As a reader, I want one Reference tab covering the Python API, CLI, configuration and exceptions, so that I don't have to guess which of two reference tabs holds FerroSettings.
47. As a reader, I want nav labels that match page titles and name what each page gives ("Testing migrations" or "Testing with Ferro", not "Testing" twice), so that search results and breadcrumbs are unambiguous.
48. As a reader, I want Why Ferro inside Get started, and the upgrade guide beside the changelog, so that the nav follows the product rather than the page history.
49. As a reader following an old link to the former migrations page, I want to be redirected to the section that replaced it, so that bookmarks keep working.
50. As a reader, I want a breadcrumb path, previous and next links in the footer, and instant page loads with a progress bar, so that moving through a section is quick.
51. As a reader who prefers the Annotated style, I want my tab choice to carry across every Assignment/Annotated pair on the site, so that I pick it once.
52. As a reader, I want tab anchors that read as words (#defining-a-model-annotated), so that I can link to a specific tab.
53. As a reader, I want hover definitions for terms such as DDL, RLS, FK, PK, GUC and FFI, so that I don't leave the page to look them up.
54. As a reader of the changelog, I want #NNN references linked to their GitHub issues, so that I can read the change behind an entry.
55. As a reader, I want a theme toggle that can follow my system setting, so that the site matches my OS.
56. As a reader, I want pages marked new or deprecated in the nav, so that I notice changes.
57. As a reader sharing a link, I want each page to carry its own description and a social card in Ferro's colour, so that previews say what the page is.
58. As a reader using an AI assistant, I want an llms.txt index and a "Copy as Markdown" action on each page, so that I can hand the docs to a tool.
59. As a reader using a screen reader, I want permalink anchors announced with a meaningful title, so that the heading links make sense.

The API reference

60. As an API reader, I want only public members listed, constructors merged into their class, and no source blocks, so that the page shows the API rather than the implementation.
61. As an API reader, I want signatures on their own line, with type annotations that link to their definitions (Ferro, Pydantic and the standard library), so that I can follow a type.
62. As an API reader, I want a symbol-type badge and a summary table at the top of each object, so that I can scan a module.
63. As an API reader, I want cross-references to render as links, not as :class: text, so that I can move between related objects.
64. As an API reader, I want every parameter in an Args: table with its default and type, including session and using, so that I don't dig through paragraphs for them.
65. As an API reader, I want every dataclass and Pydantic field documented with one line, so that report and config objects explain themselves.
66. As an API reader, I want every summary line to be one line, in the infinitive ("Fetch one record by primary key."), ending with a period, so that the reference reads as one pattern.
67. As an API reader, I want Returns: and Attributes: sections to render as proper tables, so that return values and field options are readable.
68. As an API reader, I want Field shown once rather than as six near-identical overloads, so that I can read its parameter list.
69. As an API reader, I want inherited methods such as Relation.all() and .first() to show their inherited docstring, so that they don't appear blank.
70. As an API reader, I want FieldProxy, QueryNode, RelationProxy, ValueExpr, ModelConnection, engines.session(), RunReport, StatusReport and CheckReport documented, so that every public object and every return type has an entry.
71. As an API reader, I want docstrings to stay short reference entries and link to the guide for the reasoning, so that connect, PoolConfig and Session.set_config don't open with 90-line essays.
72. As an API reader, I want the main entry points (create, get, where, save, delete, after, before, position_of, migrate) to carry an Examples section that runs, so that each one shows its use.

Maintainers and contributors

73. As a maintainer, I want CI to build the docs in strict mode, so that a broken reference or warning fails the PR.
74. As a maintainer, I want a test over the rendered site that fails on literal Sphinx roles, split return rows, dropped sections, indented snippets and undocumented exports, so that rendering regressions are caught where readers see them.
75. As a maintainer, I want a lint that fails on a one-letter lambda parameter in docs examples, inline blocks and docstring examples, so that I-8 holds without review effort.
76. As a maintainer, I want AGENTS.md I-8 to describe the lambda-only query API that exists today, so that agents stop enforcing rules for removed APIs.
77. As a maintainer, I want the docstring conventions (Google style, infinitive one-line summary, Markdown cross-references, every parameter in Args:, no internal references) written down as an AGENTS.md invariant, so that new code keeps the API reference consistent.
78. As a maintainer, I want the conventions this work settles recorded in docs/solutions/, so that the next contributor finds them (I-5): running example per page, snippet markers below the asserts, generated SQL beside the query, glossary terms.
79. As a maintainer, I want # noqa comments kept out of rendered examples, so that readers don't see lint noise.
80. As a maintainer, I want the Assignment/Annotated twins to use one Annotated idiom, so that the tabs differ only in declaration style (I-7).
81. As a maintainer, I want the skipped many-to-many documentation tests either running or deleted, so that no test is skipped for a reason pointing at a page that no longer exists.

Implementation Decisions

Dependencies. On this branch the docs dependency group and the dev group require Zensical 0.0.71, mkdocstrings-python 2.0.9 and pymdown-extensions 12.3, which brings griffe 2.3.2 (published as griffelib). The griffe-inherited-docstrings extension joins the docs group. Neither changelog breaks the current config.

Zensical configuration

• Theme features added: content.tabs.link, navigation.instant, navigation.instant.progress, navigation.tracking, navigation.path, navigation.footer, content.code.select, content.tooltips, content.action.copy.
• search.suggest is removed, because nothing in 0.0.71 reads it.
• The palette gets a third "follow system" toggle.
• extra.social links GitHub and PyPI. extra.status defines new and deprecated badges.
• Plugins added:
  • redirects, with anchor redirects that replace the hand-written redirect page for the old migrations URL; that page is deleted.
  • llmstxt.
  • social, with Ferro's rust colour as the card background.
• Every page gets front matter with a description.
• The docs build in CI runs in strict mode.
• The llmstxt Markdown copies drop content-tab labels. That is reported upstream; it does not block adoption.

Markdown extensions

• pymdownx.snippets.dedent_subsections is on.
• pymdownx.snippets.auto_append adds one glossary of abbreviations to every page. Its terms come from CONTEXT.md's language where one exists.
• pymdownx.tabbed uses combine_header_slug with a lower-case slugify.
• abbr is on.
• pymdownx.magiclink points at syn54x/ferro-orm.
• toc.permalink_title is set.
• def_list, footnotes, pymdownx.blocks.caption and pymdownx.saneheaders are turned on by the first page that needs them.
• arithmatex, caret, tilde, critic, tasklist and the blocks.* admonition syntax are not adopted. No page uses math, and the existing !!! and === syntax covers the rest.

mkdocstrings and griffe

• Inventories: Python, plus Pydantic's.
• Options:
  • filters = "public"
  • merge_init_into_class with ignore_init_summary
  • separate_signature, show_signature_annotations, signature_crossrefs
  • show_symbol_type_heading, show_symbol_type_toc
  • summary
  • backlinks = "tree"
  • scoped_crossrefs, relative_crossrefs
  • show_source = false
  • show_if_no_docstring = false, once every public object has a docstring
• Extensions: griffe-inherited-docstrings.
• Directive-level options: show_overloads: false on Field, and parameter_headings on Field, so guides can link straight to one option.
• Not adopted:
  • griffe-pydantic: it hides field constraints and lists a private validator.
  • unpack_typeddict and griffe-typingdoc: both crash the build.
  • griffe-sphinx: Sphinx roles are converted to Markdown cross-references rather than kept.
  • generics, modernized-annotations and the public-alias extensions: they change nothing for Ferro.
• griffe-warnings-deprecated is adopted in the same change that moves Ferro's deprecation helper onto the standard library's warnings.deprecated, not before.

CLI help text renders as plain text, not Markdown, in both the root app and the migrate app, so placeholders survive. Command docstrings follow the same writing rules as API docstrings.

Docstring conventions, written into AGENTS.md as a new invariant beside I-7, I-8 and I-13:

• Google style as griffe parses it.
• A one-line summary in the infinitive, ending with a period.
• Every parameter in Args:.
• Every public dataclass or Pydantic field gets a one-line docstring.
• Cross-references as Markdown autorefs, never Sphinx roles.
• No ADR numbers, issue numbers, codenames or Rust internals.
• Examples use the lambda style and the docs' running example.
• Explanations longer than a paragraph move to a guide or concepts page and are linked.

AGENTS.md I-8 is rewritten to the lambda-only API that exists: lambda predicates, the parameter named after the model in lowercase singular, and order_by's string or lambda selector. The col() and operator-style clauses and the "slated for deprecation" text go. The writing-for-agents rules apply to the edit. The Queries guide's predicate-styles section and the Typed Query Predicates concepts page change to match.

Information architecture

• The nav becomes these tabs:
  • Get started: Why Ferro, installation, quickstart.
  • Guide
  • How-to
  • Concepts
  • Reference: Python API, CLI, configuration, exceptions.
  • Project: FAQ, roadmap, upgrading between versions, changelog, contributing.
• Labels are sentence case and match their page's H1.
• Adopting migrations moves under Schema management.
• Same-named pages get distinct names: "Testing with Ferro" and "Testing migrations"; API pages are named after their object.
• The Next steps page is folded into the quickstart's closing section.

Page structure

• The row-level security guide splits into an explanation, a how-to and a reference.
• The migrations guide splits into the tutorial loop, separate how-tos (squash gets its own page) and reference tables.
• Reference tables that today appear in two or three places each get one home in Reference and are linked from the guides: the auto-migrate matrix, the PassReport kinds, the migration header table, the exit codes, the door comparison and the expand/contract table.

Running examples

• Each guide page declares one model set at the top and reuses it.
• The API reference and docstring examples share one running example, declared once and preloaded by the docs examples harness.
• Snippet section markers move below the asserts or prints that hold each result, so the page shows the answer.
• Example data uses about four real-looking rows with distinct totals.

Generated SQL is shown beside each query and each schema feature. It is captured from what Ferro actually runs, not written by hand, so the test that runs the example also produces the SQL it shows.

The field type table is generated from the storage resolution function the emitters already share (I-1 item 3), over both dialects, and the page embeds the result.

Content fixes cover every high-severity finding in the audit: the facts and recipes listed in user stories 9–27, and the snippet-level breakages (the ForeignKey docstring example, undefined names in docstring examples, the raw SQL table names, the aggregations comment that contradicts its assert, and the row-level security example's undeclared membership table).

Testing Decisions

A good test here checks what a reader gets, not how the site is built:

• the page renders as intended
• the block runs and produces what the page claims
• the quoted file matches what the tool writes
• the help text prints its placeholders

No test inspects the docs config or the Markdown source for its own sake.

Seam 1: the built site (new).

• One test module builds the site in strict mode into a temporary directory, once per session.
• It asserts over the rendered HTML: no literal Sphinx roles, no Returns: or Attributes: table with sentence-fragment rows, no snippet <code> whose lines all share leading indentation, an API entry for every name in ferro.__all__ and ferro.migrations.__all__, and no unresolved cross-reference.
• It runs in the docs CI job.
• Prior art: the strict build the publish-docs workflow already runs, and the existing documentation feature tests.

Seam 2: the docs examples harness (extended).

• Inline blocks that do real work run through the harness's existing {test=run} opt-in, or move into example scripts. A block left as compile-only states why in its marker.
• A lint over example scripts, inline blocks and docstring examples fails when a lambda passed to a query method (where, select, order_by, include, exists and the others) takes a one-letter parameter.
• An error-check pattern fails when the expected error is not raised.
• Docstring examples are collected with pytest-examples, already a dev dependency, and run against the shared running example inside a session.
• Twins are checked for equivalent models, the way the migration pairs already are.
• The testing how-to's fixtures run in a real test.
• Prior art: the existing docs examples harness, and the migration twin-equivalence check.

Seam 3: the migrations docs harness (extended).

• Each quoted generated step file is regenerated from the example models in a scratch project and compared after normalising timestamps.
• Each --help text a page quotes is compared with the CLI's actual output, and asserted to contain its placeholders.
• Prior art: the harness already pins every quoted CLI output block. The adopting-migrations page is the model for pinned output.

Field type table: a test generates the table from the storage resolution function and compares it with what the page embeds. Prior art: the cross-emitter type parity tests.

Reviewed, not tested: page kind, opening sentence, lead-in and result sentences, headings, minimising words and admonition use are checked in review against writing-for-humans. The review of each ticket that touches a page cites the rule numbers it applied.

Out of Scope

• Versioned docs (a version selector). Today it needs a mike fork that pushes to gh-pages, which clashes with the current Pages deploy. Zensical has native versioning on its roadmap; this is revisited when it ships.
• griffe-pydantic. Its trade-offs (hidden constraints, a listed private validator) outweigh the sections it adds. Revisit if those are fixed upstream.
• Math rendering (arithmatex). No page contains math.
• Changing Ferro's runtime behaviour. Where the audit found a doc and the code disagreeing, the doc changes. The one exception is the CLI help-format setting, which is user-facing text. Where a finding is unverified (the RLS round-trip count and which open transactions receive a new set_config value), the ticket confirms the code's behaviour first and documents it.
• CHANGELOG.md edits. I-10 still applies; release tooling records this work.
• The internal docs trees (ADRs, brainstorms, plans, research, solutions) are not part of the published site, so they are not audited or rewritten. Only links from published pages into them change.

Further Notes

• The audit report, which has line-level findings, rule numbers and suggested fixes for every page, example and module, is at https://claude.ai/artifact/TgPXfCFqL5VAUPmHEhqsCv. Tickets should cite its section numbers (01–13).
• Python-Markdown needs a blank line before a list and 4-space indentation for a nested list. A list that breaks either rule renders as a paragraph. The pages haven't been scanned for this yet; the ticket that adds the rendered-site test should include the check.
• The suggested order of work:
  1. Config-only changes, which fix the indentation, the build warning, the API noise, tab linking and the CLI placeholders in one small PR.
  2. Correctness, plus the I-8 rewrite.
  3. The three test seams.
  4. The docstring pass.
  5. Page restructuring.

Spec deltas

• MODIFIED: captured SQL beside each query ships on four pages (Queries, Aggregations, Relationships, Mutations) in this epic; the remaining query-running pages and the hand-typed RLS and upgrading blocks are Docs: captured SQL beside the queries on the remaining pages (pagination, soft-deletes, timestamps, transactions, connections, quickstart, RLS, upgrading) #778. (Narrowing approved 2026-10-21.)
• MODIFIED: mkdocstrings filters is ["!^_", "!^model_config$"] rather than "public", because griffe treats dunders as public; the public-surface outcome is tested.
• ADDED: the sql fence marker -- <example>.py:<snippet> (<dialect>) and tests/test_docs_sql.py, regenerating every marked block from the example's own .sql() or the statement log (Show captured SQL beside query and mutation examples (needs #700) #725).
• MODIFIED (behaviour, declared on PR fix: panel round 1 on #777 (src) — restore status flags, PoolConfig.validate and the no-route message; save(only=) in field order; docstring fences marked #779): save(), save(only=), save(exclude=) and bulk_create() list their columns in model field order, so save(only=) / save(exclude=) send the same statement text in every process (save(only=) / save(exclude=) emit columns in set order, so the UPDATE text changes between runs #776; update() keeps the call's keyword order, unchanged); the routeless-operation RuntimeError text reads "… removed in v0.14 (deprecated since v0.12); see the upgrade guide." (the old text named v0.13 and a removed page). Session.query is typed type[M] -> Query[M]; the private module ferro.migrations.chunked is _chunk_loop. All four are in the upgrade guide's 0.26 section.
• REMOVED: none.