docs: one page for a coding assistant, and a copy-page control on every page

[AlexeyShalaev]

Three things, one docs change.

A "Copy page" control above every page. It copies the page as Markdown, or opens it in
ChatGPT / Claude / Perplexity. It works because scripts/emit_markdown.py runs after the
build and writes every docs/<path>.md next to the HTML it built, so each page has a
plain-text twin one URL away: /agents/ and /agents.md, /guide/configuration/ and
/guide/configuration.md. The Docs workflow gains that one step.

docs/agents.md — the whole library on one page, written for a coding assistant. The
public surface, the session-lifetime and transaction-ownership rules, the mistakes a model
actually makes with a Unit of Work, and a map of which page to fetch for the rest. Every
name on it is checked against sqlalchemy_foundation_kit.__all__; the top-level table is
exactly those 40 names, nothing invented and nothing left out. It is in the nav as "For AI
agents", right under Home, and linked from the README.

The API reference declines both the control and the twin (copy_page: false): its
Markdown is a list of instructions to mkdocstrings, not the API, so a model fetching
/reference.md would learn nothing.

The rule that keeps it honest. CONTRIBUTING.md gains a section saying the page is
part of the public API and goes stale in the same pull request that changes it — a stale
one is worse than none, because it teaches a model an API that no longer exists. The pull
request checklist now names the file.

What the page reports that the code does, and the docs do not

Writing it against the source turned up five things worth their own issues. The page states
them because it has to be true; none of them are fixed here.

1. import sqlalchemy_foundation_kit fails on a clean install — session/connection.py
   imports asyncpg at module scope and asyncpg is not in dependencies.
2. AsyncSessionManager.get_transaction() raises TypeError on every call, with or
   without an isolation level: it passes execution_options= to the session factory, and
   Session.__init__ has no such argument. The README, the index and the quick start all
   show it as the primary write path.
3. uow.transaction(isolation_level=...), managed_session(...) and query(...) raise
   InvalidRequestError: apply_isolation_level calls session.connection(), which
   autobegins, and then tries to set the level on a connection that already has a
   transaction. Only engine-level isolation_level works today.
4. A string advisory-lock key is hashed with hash(), which is salted per process, so two
   replicas take different locks and both proceed. guide/advanced.md recommends string
   keys for exactly the case this breaks.
5. contrib.di and contrib.dependency_injector fail on import without their extra with a
   bare AttributeError instead of the ImportError check_dishka() was written to give.

How to see it

The Docs workflow deploys on merge; the control and the page are live at
https://bedrock-python.github.io/sqlalchemy-foundation-kit/agents/ once it does. Locally:

uv sync --no-dev --group docs --frozen
cp CHANGELOG.md docs/changelog.md
uv run --no-sync zensical build --clean
uv run --no-sync python scripts/emit_markdown.py

zensical serve rebuilds into the same directory without the emit step, so a served
preview answers 404 to the control — build the site to try it.

docs/assets/stylesheets/copy-page.css, docs/assets/javascripts/copy-page.js,
overrides/main.html and scripts/emit_markdown.py are byte-identical across the
organisation on purpose, so they can be updated in one sweep. uv.lock is untouched.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!