feat: new libraries ship the agents page and the copy-page control (#6)

Author: AlexeyShalaev

.claude/LIBRARY_CREATION.md

@@ -73,7 +73,28 @@ When creating a new library repository:
 - First `feat:` commit → Release Please creates v0.1.0
 - First `fix:` commit → Release Please creates v0.0.1
 
-## 5. Clean Repository Checklist
+## 5. The Agents Page
+
+`docs/agents.md` ships as a skeleton with `TODO` markers. Fill it in before the initial
+commit — it is the page a person hands to a coding assistant instead of the whole site,
+so an empty one is a broken promise and a wrong one teaches an API that does not exist.
+
+Write it from the source you just wrote, not from the README: every name, argument,
+default and return type has to be one that exists, and every name a caller is told to
+import has to be importable. Check that before committing:
+
+```bash
+uv run python -c "import <package>; [getattr(<package>, n) for n in ('Name', ...)]"
+```
+
+`https://bedrock-python.github.io/pg-partsmith/agents/` is the worked example. The
+sections that carry the weight are **Scope** (what it does not do stops a model
+inventing features), **Rules that hold or break the code** and **Common mistakes**.
+Delete a section that has nothing true to say rather than padding it.
+
+Keep the `<!-- ... -->` guidance comment out of the committed page.
+
+## 6. Clean Repository Checklist
 
 Before pushing the initial commit, verify:
 
@@ -83,8 +104,9 @@ Before pushing the initial commit, verify:
 - [ ] No backup files (e.g., `.coverage (копия...)`, `file (copy).py`)
 - [ ] No cache files (`.mypy_cache`, `.ruff_cache`, `__pycache__`) - should be in `.gitignore`
 - [ ] `.release-please-manifest.json` contains `"0.0.0"`
+- [ ] `docs/agents.md` written from the real API, no `TODO` markers, guidance comment removed
 
-## 6. PyPI Publication
+## 7. PyPI Publication
 
 Before merging the Release Please PR:
 
@@ -97,15 +119,16 @@ Before merging the Release Please PR:
 
 2. Merge Release Please PR → automatic publication to PyPI
 
-## 7. Common Mistakes to Avoid
+## 8. Common Mistakes to Avoid
 
 ❌ Including AI agents in commits
 ❌ Committing `scripts/setup_repo.py` to the library repo
 ❌ Starting with version `0.1.0` instead of `0.0.0`
 ❌ Committing backup/cache files
 ❌ Creating multiple commits before initial push (messy history)
+❌ Shipping `docs/agents.md` with its `TODO` markers still in it
 
-## 8. Summary
+## 9. Summary
 
 **Clean initial commit = Clean repository forever**
 

NEW_LIBRARY_CHECKLIST.md.jinja

@@ -10,6 +10,16 @@ uv run pre-commit install --hook-type commit-msg
 make check      # should pass on a fresh repo
 ```
 
+Then fill in `docs/agents.md`. It ships as a skeleton with `TODO` markers, and it is the
+page people hand to a coding assistant instead of the whole site — write it from the API
+you actually wrote, verify every name it tells a caller to import, and delete the
+guidance comment at the top. `https://bedrock-python.github.io/pg-partsmith/agents/` is
+the worked example. `CONTRIBUTING.md` keeps it current from there.
+
+```bash
+make docs-build   # the page is in the nav, so the build fails without it
+```
+
 ## Step 2 — Create GitHub repo and push
 
 ```bash

README.md

@@ -72,6 +72,8 @@ See [`.claude/LIBRARY_CREATION.md`](.claude/LIBRARY_CREATION.md) for important r
 - `Makefile` — fmt, check, test-unit, test-integration, test, build, docs-serve, docs-build
 - `.github/workflows/` — CI (lint + unit + integration), publish to PyPI, deploy docs, Release Please
 - `.github/` — dependabot, issue templates, PR template
-- `docs/` — zensical (MkDocs Material) setup with mkdocstrings
+- `docs/` — zensical (MkDocs Material) setup with mkdocstrings, a **Copy page** control that
+  hands any page to an LLM as Markdown, and `docs/agents.md`, the one-page brief for coding
+  assistants (ships as a skeleton — fill it in)
 - `.pre-commit-config.yaml` — ruff, mypy, conventional commits
 - `release-please-config.json` — automated semver + CHANGELOG generation

template/.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
 

template/.github/workflows/docs.yml

@@ -18,6 +18,7 @@ jobs:
       - run: uv sync --no-dev --group docs
       - run: cp CHANGELOG.md docs/changelog.md
       - run: uv run zensical build --clean
+      - run: uv run python scripts/emit_markdown.py
       - uses: actions/upload-pages-artifact@v5
         with:
           path: site

template/CONTRIBUTING.md.jinja

@@ -52,6 +52,26 @@ Breaking changes: add `!` after the type (`feat!:`) or include a `BREAKING CHANG
 4. Run `make check && make test-unit` locally
 5. Open a PR against `master`
 
+## 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.
+
 ## Releasing (maintainers only)
 
 Releases are fully automated via [Release Please](https://github.com/googleapis/release-please).

template/README.md.jinja

@@ -9,6 +9,14 @@
 [![codecov](https://codecov.io/gh/{{ github_org }}/{{ project_slug }}/graph/badge.svg)](https://codecov.io/gh/{{ github_org }}/{{ project_slug }})
 [![Docs](https://img.shields.io/badge/docs-online-blue)](https://{{ github_org }}.github.io/{{ project_slug }}/)
 
+> [!TIP]
+> **Building this with an AI assistant?** Hand it
+> **[one page](https://{{ github_org }}.github.io/{{ project_slug }}/agents/)** instead of the
+> whole site: 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. Every docs page is also served
+> as raw Markdown at its own URL, and a **Copy page** button at the top of each one hands it
+> straight to a chat window.
+
 ## Installation
 
 ```bash
@@ -27,6 +35,10 @@ pip install {{ project_slug }}
 
 Full documentation at [{{ github_org }}.github.io/{{ project_slug }}](https://{{ github_org }}.github.io/{{ project_slug }}/).
 
+- [Guide](https://{{ github_org }}.github.io/{{ project_slug }}/guide/quickstart/) — quick start, configuration, the advanced corners
+- [API reference](https://{{ github_org }}.github.io/{{ project_slug }}/reference/) — every public name, generated from the docstrings
+- [For AI agents](https://{{ github_org }}.github.io/{{ project_slug }}/agents/) — the whole API surface, the rules that break code when broken and a map of the rest, on one page to hand to a coding assistant
+
 ## License
 
 Apache 2.0 — see [LICENSE](LICENSE).

template/docs/agents.md.jinja

@@ -0,0 +1,106 @@
+<!--
+  This page is the one people hand to a coding assistant instead of the whole site,
+  which is what makes an inaccurate one worse than none: it teaches a model an API
+  that does not exist. Two rules while filling it in.
+
+  Write it from the source, not from memory. Every name, argument, default and
+  return type here has to be one you read in {{ package_name }}/, and every name a
+  caller is told to import has to be importable. Delete a section that carries
+  nothing rather than padding it.
+
+  Keep it current. CONTRIBUTING.md says this page changes in the same pull request
+  the public API does; the pull request checklist names it. That promise is the only
+  thing keeping the page worth handing over.
+
+  bedrock-python.github.io/pg-partsmith/agents/ is the worked example to copy the
+  shape from. Delete this comment once the page says something.
+-->
+
+# {{ project_name }} for AI agents
+
+> One page holding everything a coding assistant needs to use {{ project_name }}
+> correctly, plus a map of where the rest of the documentation keeps the details it
+> leaves out. Give an agent this page rather than the whole site.
+
+| | |
+|---|---|
+| Package | `{{ project_slug }}` on PyPI, import root `{{ package_name }}` |
+| Requires | Python {{ python_min_version }}+ |
+| Install | `pip install {{ project_slug }}` |
+| Source | <https://github.com/{{ github_org }}/{{ project_slug }}> |
+
+## How to read this page
+
+Every page of this site is also served as raw Markdown at its own URL with `.md` in
+place of the trailing slash — this page is `/agents.md`, the quick start is
+`/guide/quickstart.md` — so anything the map below points at can be fetched as plain
+text rather than scraped out of HTML. The **Copy page** control at the top of a page
+does the same thing for a human with a chat window open. The one exception is the API
+reference: its Markdown is a list of instructions to a docstring renderer rather than
+the API, so it carries neither the control nor a `.md` twin — read it as HTML, or read
+the docstrings in the source.
+
+Top to bottom before writing code. [Rules that hold or break the code](#rules-that-hold-or-break-the-code)
+is the section correctness lives in — those are the things the library will not save
+you from. Every name used below is in the public API; if you need something not listed
+here, fetch the page the [documentation map](#documentation-map) points at rather than
+guessing a method that sounds plausible.
+
+## Scope
+
+**It does** TODO: what the library is for, in the vocabulary a caller thinks in.
+
+**It does not** TODO: the neighbouring problems it deliberately leaves alone. This
+paragraph stops a model from inventing a feature; it is worth more than the one above.
+
+## Mental model
+
+TODO: the handful of nouns the API is built from and the flow between them. Name each
+type once and say what it owns.
+
+## Wiring
+
+```python
+# TODO: the shortest correct working example, imports included. It has to run.
+```
+
+## API
+
+TODO: tables, not prose. Every public name a caller needs, with its arguments, their
+defaults and what comes back. Read the defaults out of the source rather than
+remembering them.
+
+| Name | Arguments | Returns |
+|---|---|---|
+| | | |
+
+## Rules that hold or break the code
+
+TODO: numbered, one rule per item, each one a thing the library will not save a caller
+from — an object that must not be shared, an argument whose default surprises people, a
+call that has to be repeated until it says it is finished, a lifetime that is the
+caller's to manage. Write the ones that are true here, not the ones that sound wise.
+
+## Common mistakes
+
+```python
+# WRONG — TODO: the mistake a model actually makes with this API
+
+# RIGHT — TODO: the same thing, done properly
+```
+
+## Errors
+
+TODO: the exception classes, what each one means, and what a caller should do about it.
+
+## Documentation map
+
+Fetch a page when the task is the one named beside it.
+
+| Page | Read it when |
+|---|---|
+| [Quick start](guide/quickstart.md) | writing the first integration end to end |
+| [Configuration](guide/configuration.md) | every setting, type and default |
+| [Advanced](guide/advanced.md) | TODO: what this page actually covers |
+| [API reference](reference/index.md) | an exact signature or docstring — HTML only, see above |
+| [Changelog](changelog.md) | what changed between versions |