Add repository instructions for coding agents

AGENTS.md

@@ -0,0 +1,72 @@
+# Working on Bootstrap-Flask
+
+Bootstrap-Flask provides Flask extension classes and Jinja macros for Bootstrap 4
+and 5. The distribution is `Bootstrap-Flask`; the Python package is
+`flask_bootstrap`. Do not install `Flask-Bootstrap` in the same environment: both
+projects use that package name.
+
+## Repository layout
+
+- `flask_bootstrap/__init__.py`: extension initialization, configuration, asset
+  loading, and Python helpers.
+- `flask_bootstrap/templates/base/`: shared macros. `bootstrap4/` and `bootstrap5/`
+  contain version-specific macros and wrappers; `bootstrap/` is the deprecated
+  Bootstrap 4 compatibility path.
+- `flask_bootstrap/static/`: bundled Bootstrap, Bootswatch, Popper, jQuery, and icon
+  assets, separated by Bootstrap version.
+- `tests/`: pytest tests, with shared fixtures in `conftest.py` and extension
+  fixtures in `test_bootstrap4/` and `test_bootstrap5/`.
+- `docs/`: Sphinx documentation in reStructuredText. `examples/bootstrap4/` and
+  `examples/bootstrap5/` contain runnable demo applications.
+- `pyproject.toml`, `MANIFEST.in`, and `CHANGES.rst`: package metadata, packaged
+  assets, and release history. `tox.ini` and `.github/workflows/` define checks.
+
+## Development and validation
+
+Use Python 3.11 or newer; the current test matrix covers 3.11 through 3.14. From
+the repository root, the development setup documented in `docs/index.rst` is:
+
+```sh
+python3 -m venv venv
+. venv/bin/activate
+python -m pip install -e .
+python -m pip install -r requirements/dev.txt
+```
+
+Reuse an existing suitable environment when available. Run checks appropriate to
+the change:
+
+```sh
+python -m pytest                                      # full test suite
+python -m pytest tests/test_bootstrap5/test_render_form.py  # focused example
+tox -e flake8                                        # Python style checks
+tox -e docs                                          # Sphinx, warnings as errors
+tox                                                  # configured full checks
+```
+
+Tox skips unavailable Python interpreters, so report what actually ran. The
+coverage environment is currently spelled `covarage`: use `tox -e covarage` when
+checking coverage. CI tests Linux, macOS, and Windows.
+
+## Making changes
+
+- Check both Bootstrap versions when changing shared behavior. Form macros have
+  separate implementations; shared table, navigation, pagination, and utility
+  changes may affect both versions through inheritance or imports. Preserve
+  version-specific markup instead of copying Bootstrap 5 classes into Bootstrap 4.
+- Follow existing pytest fixtures and HTML assertions. For behavior changes,
+  add focused regression coverage in the relevant version suites and run related
+  tests before the full suite.
+- Keep public macro arguments, configuration keys, and compatibility wrappers in
+  mind. Document public behavior changes in the relevant `docs/` pages and
+  describe user-visible changes in `CHANGES.rst`.
+- Follow `.flake8`: maximum Python line length is 119 and maximum complexity is
+  7. Preserve existing license notices in inherited macros.
+- Requirement `.txt` files are generated by `pip-compile-multi`. Edit the
+  corresponding `requirements/*.in` sources and regenerate intentionally; avoid
+  unrelated dependency churn.
+- For asset updates, check version constants, CDN URLs, integrity values, bundled
+  files, and local-serving behavior together. Ensure new templates and static
+  assets remain covered by `MANIFEST.in`.
+- Keep changes scoped to the requested task. In the handoff or pull request,
+  explain the resulting behavior, checks performed, and any checks not run.