docs: the agents page is part of the public API, and one shared copy-page script

.github/PULL_REQUEST_TEMPLATE.md

@@ -15,7 +15,7 @@
 - [ ] Tests added or updated
 - [ ] `make check` passes locally (`ruff` + `mypy`)
 - [ ] `CHANGELOG.md` updated under `[Unreleased]`
-- [ ] Documentation updated (if the public API changed)
+- [ ] Documentation updated (if the public API changed), `docs/agents.md` included
 
 ## Related issues
 

CONTRIBUTING.md

@@ -54,6 +54,26 @@ Breaking changes: add `!` after the type (`feat!:`) or include a `BREAKING CHANG
 
 Update `CHANGELOG.md` under `[Unreleased]` for any user-visible change.
 
+## The agents page
+
+`docs/agents.md` is the whole library on one page, written for a coding assistant: the
+public API, the rules that break code when they are broken, the mistakes models make, and
+a map of which page to fetch for the rest. People hand it to an assistant instead of the
+site, which is what makes a stale one worse than none — it teaches a model an API that no
+longer exists.
+
+It is part of the public API, so it changes in the same pull request the API does: a name
+added, renamed or removed, a changed default or signature, a new rule a caller has to
+obey. A new docs page means a new row in the documentation map. The review check is
+mechanical — if the diff changes the public surface and `docs/agents.md` is untouched, the
+pull request is not finished.
+
+The page carries its own weight only if it stays fetchable as text. Every page of the site
+is written a second time as raw Markdown next to its HTML by `scripts/emit_markdown.py`,
+which the Docs workflow runs after the build; the **Copy page** control above each page
+reads those files. A page whose Markdown would not read as the page — the generated API
+reference — declines both with `copy_page: false` in its front matter.
+
 ## Integration tests
 
 Integration tests use [testcontainers](https://testcontainers.com/) to spin up a real

docs/agents.md

@@ -230,7 +230,7 @@ Nesting is `child=`, up to five levels including the root.
 
 | Axis | Constructor |
 |---|---|
-| Calendar over a timestamp | `TimeBoundaries(granularity=… \| calculator=…, tz="UTC", codec=None)` |
+| Calendar over a timestamp | `TimeBoundaries(granularity=… | calculator=…, tz="UTC", codec=None)` |
 | Calendar over an encoded key | the same, with `codec=UUIDv7BoundaryCodec()` or `EpochBoundaryCodec(unit)` |
 | Fixed-width integer windows | `NumericBoundaries(step, origin=0, name_suffix="__{start}", cursor_source=…)` |
 | One value per partition | `IntegerSequence(start=1, name_suffix="__{value}", cursor_source=…)` |
@@ -268,12 +268,12 @@ Every method takes the `TablePartitionConfig` as its first argument.
 
 | Method | Lock | DDL | Returns |
 |---|---|---|---|
-| `inspect(config)` | no | no | `ActualTree \| None` |
+| `inspect(config)` | no | no | `ActualTree | None` |
 | `plan(config, *, mode=PlanMode.MAINTAIN, now=None, windows=None)` | no | no | `MaintenancePlan` |
 | `apply(config, plan, *, continue_on_error=False, allow_config_drift=False)` | **yes** | yes | `MaintenanceResult` |
 | `maintain(config, *, skip_create=False, skip_detach=False, skip_drop=False, continue_on_error=False)` | **yes** | yes | `MaintenanceResult` |
 | `reconcile(config)` | no | yes | `MaintenanceResult` |
-| `ensure_partition(config, period_or_window_or_position)` | no | yes | `PartitionInfo \| None` |
+| `ensure_partition(config, period_or_window_or_position)` | no | yes | `PartitionInfo | None` |
 | `ensure_partitions(config, periods)` | no | yes | `list[PartitionInfo]` |
 | `partition_data(config, *, batch_rows=10_000, max_batches=None)` | **yes** | yes | `MigrationResult` |
 | `unpartition(config, into, *, batch_rows=10_000, max_batches=None, drop_emptied=False)` | **yes** | yes | `MigrationResult` |

docs/assets/javascripts/copy-page.js

@@ -9,9 +9,10 @@
 
   var RESET_AFTER_MS = 2000;
 
-  /* Where the Markdown of a page is written, as an absolute URL. The pair of
-     data attributes says how far the site root is from here and where this
-     page sits below it; scripts/emit_markdown.py writes the file to match. */
+  /* Where the Markdown of a page is written, as an absolute URL. Two data
+     attributes say how far the site root is from here and where this page sits
+     below it; scripts/emit_markdown.py writes the file to match. The site's own
+     name is a third, so this file is the same in every project that carries it. */
   function markdownUrl(widget) {
     var base = (widget.dataset.copyBase || ".").replace(/\/$/, "");
     var page = widget.dataset.copyPage || "";
@@ -21,12 +22,15 @@
 
   function prompt(widget) {
     var title = widget.dataset.copyTitle || document.title;
+    var site = widget.dataset.copySite || "project";
     return (
       "Read " +
       markdownUrl(widget) +
       ' -- the "' +
       title +
-      '" page of the pg-partsmith documentation -- so I can ask questions about it.'
+      '" page of the ' +
+      site +
+      " documentation -- so I can ask questions about it."
     );
   }
 

overrides/main.html

@@ -11,7 +11,7 @@
      with `copy_page: false` in its front matter. -#}
   {% if page.meta.copy_page != false %}
   <div class="md-copy-page" data-copy-base="{{ base_url }}" data-copy-page="{{ page.url }}"
-       data-copy-title="{{ page.title }}">
+       data-copy-title="{{ page.title }}" data-copy-site="{{ config.site_name }}">
     <div class="md-copy-page__group">
       <button type="button" class="md-copy-page__button md-copy-page__button--main" data-copy-action>
         <span class="md-copy-page__icon md-copy-page__icon--idle">