ak-py-bootstrap 0.9.4__tar.gz

ak_py_bootstrap-0.9.4/.github/workflows/ci.yml

@@ -0,0 +1,84 @@
+name: ci
+
+# Runs on PRs into main / release/*, on pushes to those branches, and for the
+# merge queue (so it gates queued PRs).
+#
+# This workflow is `make check`, split across jobs so the legs run in parallel.
+# Every check is a `make` target invoked exactly as it is locally - there is no
+# check that CI enforces and `make check` does not, and none the other way
+# round. `tox` owns only the interpreter matrix, so the test job pins one
+# interpreter per leg and hands `make` the matching env rather than letting tox
+# discover interpreters itself.
+
+on:
+  pull_request:
+    branches:
+      - main
+      - "release/*"
+  push:
+    branches:
+      - main
+      - "release/*"
+  merge_group:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.event.pull_request.number || github.ref }}
+  # Cancel superseded PR runs; never cancel a merge-queue or push run.
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  # Style, annotations, the docs build and the changelog fragment. All
+  # single-interpreter, so they share one matrix over `make` targets.
+  checks:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        target: [cs, ann, doc, cl-check]
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0        # setuptools-scm (doc) and cl-check need history + tags
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      # The Makefile defaults PYTHON to python3.13; setup-python already put the
+      # interpreter we want first on PATH, so point it there instead.
+      - run: make ${{ matrix.target }} PYTHON=python
+
+  # The suite, once per supported interpreter. Each leg installs only its own
+  # interpreter, so tox never has to find a second one.
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python: "3.13"
+            toxenv: py313
+          - python: "3.14"
+            toxenv: py314
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0        # setuptools-scm needs full history + tags
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: make test PY_ENV=${{ matrix.toxenv }} PYTHON=python
+      # Reporting only - the coverage gate is `fail_under` in pyproject.toml,
+      # which `make test` already enforced above. A Codecov outage must not
+      # turn the build red, hence fail_ci_if_error: false.
+      - uses: codecov/codecov-action@v7
+        with:
+          files: ./coverage.xml
+          flags: ${{ matrix.toxenv }}
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false

ak_py_bootstrap-0.9.4/.gitignore

@@ -0,0 +1,165 @@
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/build/
+docs/modules/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+.venv-smoke
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+py_bootstrap/templates/test-bootstrap

ak_py_bootstrap-0.9.4/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-merge-conflict
+      - id: check-docstring-first
+      - id: debug-statements
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+  - repo: https://github.com/pycqa/flake8
+    rev: 7.2.0
+    hooks:
+      - id: flake8
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.16.0
+    hooks:
+      - id: mypy
+        language_version: python3

ak_py_bootstrap-0.9.4/.readthedocs.yaml

@@ -0,0 +1,38 @@
+# Read the Docs build configuration.
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  jobs:
+    # Full history + tags so setuptools-scm can resolve the version.
+    post_checkout:
+      - git fetch --unshallow || true
+      - git fetch --tags || true
+    pre_build:
+      # `make apidoc` installs the `doc` dependency group (PEP 735) and
+      # regenerates docs/modules/, which is gitignored. Pointing VENV at the
+      # environment Read the Docs already built stops make from creating a
+      # second one, and keeps the sphinx-apidoc flags defined in one place.
+      # pip must be >= 25.1 first: PEP 735 `--group` is what the target uses.
+      #
+      # Equivalent without make:
+      #   python -m pip install --group doc
+      #   sphinx-apidoc --separate --force --no-toc --module-first \
+      #       --ext-viewcode --output-dir docs/modules py_bootstrap
+      - python -m pip install --upgrade pip
+      - make apidoc VENV=$READTHEDOCS_VIRTUALENV_PATH
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false
+
+python:
+  install:
+    - method: pip
+      path: .
+
+formats:
+  - pdf

ak_py_bootstrap-0.9.4/AUTHORS.md

@@ -0,0 +1,8 @@
+Authors
+=======
+
+## Owners:
+* Aliaksandr Karotki, abkorotky@gmail.com.
+
+## Developers:
+* Aliaksandr Karotki, abkorotky@gmail.com.

ak_py_bootstrap-0.9.4/CHANGELOG.md

@@ -0,0 +1,113 @@
+# Py Bootstrap Changelog
+
+<!-- towncrier release notes start -->
+
+## [0.9.4] - 2026-09-07
+### Added
+- Added `tools/check_matrix.py`, which fails when the supported-Python list drifts apart. The interpreters are declared three times with nothing linking them — `tox.ini` `env_list`, the `pyproject.toml` classifiers and the `ci.yml` test matrix — so adding a version in one place and forgetting the others used to pass silently. `make test` runs it before handing over to `tox`.
+- Added a `CLAUDE.md` at the repository root describing the project for Claude Code: the `make`-driven command set, the mandatory `changelog.d/` news fragment, the operation-object and entry-point discovery architecture, the templating rules that are easy to get wrong (rendered destination paths, the `.tmpl` suffix, the `{empty}` dotfile placeholder), and the test fixture layout. It also sets a 200-line limit on every `CLAUDE.md` in the repository.
+- Added coverage reporting to Codecov. The suite now writes `coverage.xml` alongside the existing terminal and HTML reports, and the `ci` workflow uploads it once per interpreter. The coverage gate itself is unchanged — `fail_under = 95` still fails `make test` locally and in CI, so the upload is reporting only and a Codecov outage cannot turn the build red.
+- Declared support for Python 3.14 with a `Programming Language :: Python :: 3.14` classifier. The test suite already ran on `py314` through `tox`, but the package metadata advertised only 3.13.
+
+### Changed
+- Corrected the maintainer release docs after `release.yml` was removed. `docs/releasing/configure-github-actions.md` and `configure-pypi.md` described a release pipeline that no longer exists and listed `tools/` scripts that were never written; both now open with a "not implemented" admonition and read as a design record. The contributing guide documents the actual flow, which is `make release` from a clean checkout.
+- Extended the code style and annotation checks to `tools/`. `make format`, `make cs` and `make ann` previously covered only `py_bootstrap/` and `tests/`, leaving the release and check scripts unchecked.
+- Folded the separate `changelog` workflow into `.github/workflows/ci.yml` as another `make cl-check` leg, and dropped the `skip-changelog` label bypass. The `ci` workflow is now exactly `make check` split across parallel jobs, so a check either fails in both places or neither — `make check` also runs `doc`, which previously only ran on GitHub.
+- Switched the default release index to the real PyPI. `make dist-upload` and `make release` now upload to `pypi` instead of `testpypi`; pass `PYPI=testpypi` to rehearse a release against the sandbox index.
+- Upgraded the `ci` workflow to `actions/checkout@v7` and `actions/setup-python@v7`. The previous major versions target Node.js 20, which GitHub has deprecated, so every job emitted a warning and was silently forced onto Node.js 24.
+
+### Fixed
+- Corrected the Read the Docs setup guide on two settings that silently stop automatic builds: the project must use a **Connected repository** rather than a manually configured repository URL, which leaves it with no GitHub integration at all, so no push or tag event ever reaches Read the Docs; and the `.readthedocs.yaml` path field takes a path relative to the repository root, not a URL. Also clarified that a version being *Hidden* and being *Active* are independent settings.
+- Fixed the `ci` GitHub Actions workflow, which invoked `tox` environments (`cs`, `ann`, `utc`, `doc`) that `tox.ini` does not define, so every run failed. The checks now go through `make`, matching how they are documented and run locally, and the suite runs once per supported interpreter with only that interpreter installed.
+
+## [0.9.3] - 2026-09-06
+### Added
+- Added `docs/static/rtd-flyout.js`, which removes the "On Read the Docs" section (Project Home, Builds) from the Read the Docs flyout menu. Read the Docs offers no setting for this and the flyout exposes no CSS hooks, so it is done with a small script loaded through `html_js_files`.
+
+### Changed
+- Documented building the published documentation from release tags: `stable` as the default Read the Docs version, activating `v*` tag versions, and hiding `latest` so readers are offered documentation matching a released artefact. The README badge and link now point at `stable`.
+
+## [0.9.2] - 2026-09-06
+### Added
+- Added `docs/releasing/configure-readthedocs.md`, a setup guide for hosting the documentation on Read the Docs: creating the project, verifying the first build, the version and automation-rule settings, pull request previews, and troubleshooting.
+- Added a `make apidoc` target that regenerates the `docs/modules/` API stubs. `make doc` depends on it and Read the Docs calls it with `VENV=$READTHEDOCS_VIRTUALENV_PATH`, so the `sphinx-apidoc` flags are defined once instead of being duplicated in `.readthedocs.yaml`, and Read the Docs no longer needs a second virtualenv.
+
+### Changed
+- Changed the `towncrier` output template so generated `CHANGELOG.md` sections match the compact style of the hand-written history: no blank line after the version or category headings, one blank line between categories.
+
+### Fixed
+- Fixed the Read the Docs build: `.readthedocs.yaml` installed a `docs` dependency group, but the group in `pyproject.toml` is named `doc`. Every build failed at the `pre_build` step with `Dependency group 'docs' not found`.
+
+## [0.9.1] - 2026-09-06
+### Added
+- Added GitHub Actions workflows: `ci` (style, types, tests and docs on every pull request), `changelog` (fails a pull request that adds no news fragment) and `release` (builds and publishes to PyPI through Trusted Publishing on a `v*` tag, then creates the GitHub Release).
+- Added a `Makefile` as the task runner for development and release work. Targets install the PEP 735 dependency group they need on demand into a single virtualenv, so the toolchain is no longer duplicated per task. Run `make` for the full list.
+- Added release tooling under `tools/`, driven by the `Makefile`: `check_version.py` rejects a version that is not PEP 440 or whose tag already exists locally or on the remote, `check_no_diff.py` refuses to release from a dirty working tree, and `smoke.py` installs the freshly built wheel into a throwaway virtualenv and exercises the console script. `make release VERSION=X.Y.Z` chains the tag, build and upload steps; `make dist-build` and `make dist-upload` are usable on their own.
+- Adopted `towncrier` for changelog management. Document user-facing changes by adding a news fragment under `changelog.d/` (see `changelog.d/README.md`); the release flow collates them into `CHANGELOG.md`.
+
+### Changed
+- Project version is now derived from git tags via `setuptools-scm`. The hand-maintained `NAME`, `TITLE`, `DESCRIPTION`, `VERSION`, `PY_VERSION`, `AUTHOR` and `AUTHOR_EMAIL` constants were removed from `py_bootstrap/__init__.py`; consumers read `importlib.metadata` instead.
+- Reduced `tox.ini` to the interpreter matrix (`py313`, `py314`) running the test suite. Every other task moved to the `Makefile`.
+- Reworked the documentation: the Sphinx site is now MyST Markdown with installation, quickstart, guides, concepts and API reference sections, published on Read the Docs via `.readthedocs.yaml`. The hand-written `docs/modules/*.rst` stubs are generated by `sphinx-apidoc` at build time instead of being committed.
+
+### Removed
+- Removed `requirements.txt` and `requirements-dev.txt`. Dependencies are declared in `pyproject.toml` as PEP 735 dependency groups; install them with `pip install -e . --group dev` or `make deps`.
+
+## [0.9.0] - 2025-11-02
+### Changed
+- Move `name` and `description` CLI arguments processing from `BaseBuildBootstrapOperation` to `DefaultBuildBootstrapOperation`. See `py_bootstrap/operations/build_bootstrap.py` file for details.
+
+## [0.8.0] - 2025-09-13
+### Added
+- Add `tox.ini` to `application` bootstrap. See `py_bootstrap/templates/application/tox.ini` file for details.
+- Add `tox.ini` to `package` bootstrap. See `py_bootstrap/templates/package/tox.ini` file for details.
+
+### Changed
+- `underscored_name` placeholder is replaced to `python_name` in all templates and corresponding builders. see `py_bootstrap/templates/` directory for details.
+
+## [0.7.0] - 2025-06-24
+### Changed
+- Convert `templates` directory into a Python package. See `py_bootstrap/templates/__init__.py` file for details.
+- Implement getting a list of bootstraps from setuptools plugins. See `py_bootstrap/operations/base.py` file for details.
+
+## [0.6.1] - 2025-06-24
+### Changed
+- Refactor `README.md` files in `application`, `package`. See `py_bootastrap/templates/` directory for details.
+- Refactor project's `README.md` file. See `README.md` for details.
+
+## [0.6.0] - 2025-06-24
+### Added
+- Actualize `README.md` file. Prepare `Using` and `For Development` sections.
+- Refactor implemented bootstraps for unification, fix small bugs and actualize help data. See `py_bootstrap/templates` directory for details.
+- Implement `bootstrap` template for developing bootstraps from scratches. See `py_bootstrap/templates/bootstrap/` directory for details.
+- Implement exporting bootstraps templates operation. See `py_bootstrap/operations/export_bootstrap.py` file for details.
+
+## [0.5.0] - 2025-06-23
+### Added
+- Implement `FilesProcessors` functionality. See `py_bootstrap/files_processors/` directory for details.
+
+### Changed
+- Refactor operations functionality. See `py_bootstrap/operations/` directory for details.
+- Rename `BaseOperationsDispatcher` to `BaseRecursiveOperationsContainer`, move it in a separated file. See `/py_bootstrap/base/operations/recursive_container.py` file for details.
+
+## [0.4.0] - 2025-06-02
+### Added
+- Implement `RegisterBootstrapOperation` class for registering new customer's bootstraps. See `/py_bootstrap/operations/register_bootstrap.py` file for details.
+- Prepare `template` bootstrap structure. See `/py_bootstrap/templates/template/` directory for details.
+
+## [0.3.0] - 2025-06-01
+### Added
+- Prepare `application` bootstrap structure. See `/py_bootstrap/templates/application/` directory for details.
+
+## [0.2.0] - 2025-06-01
+### Added
+- Prepare `package` bootstrap structure. See `/py_bootstrap/templates/package/` directory for details.
+- Implement `BuildBootstrapOperation` class for generating a given bootstrap. See `/py_bootstrap/operations/build_bootstraps.py` file for details.
+- Implement `ListBootstrapsOperation` class for printing enabled bootstraps. See `/py_bootstrap/operations/list_bootstraps.py` file for details.
+- Implement the main script for running bootstrap operations. See `/py_bootstrap/scripts/bootstrap.py` file for details.
+- Implement base functionality for operations. See `/py_bootstrap/base/operations.py` file for details.
+- Implement the main CLI entrypoint. See `/py_bootstrap/cli_entrypoint.py` file for details.
+
+## [0.1.0] - 2024-06-08
+### Added
+- Prepare a common skeleton based on tox automation.

ak_py_bootstrap-0.9.4/CLAUDE.md

@@ -0,0 +1,128 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## File Size Rule
+
+Applies to **every** `CLAUDE.md` in this repo — this file is always loaded, so the rule is stated
+once here and never repeated in the per-directory files.
+
+- Maximum limit: 200 rows/lines.
+- Never add notes, logs, or explanations that push the file over this limit.
+- Delete old or unused instructions before adding new ones.
+- Don't duplicate info between CLAUDE.md files — document a thing in the directory that owns it and
+  link to it from elsewhere.
+
+## What this is
+
+`ak-py-bootstrap` — a zero-runtime-dependency CLI (`bootstrap`) that generates Python
+project skeletons from *bootstraps* (templates). Python >= 3.13 only. Package dir is
+`py_bootstrap/`; distribution name is `ak-py-bootstrap`.
+
+## Commands
+
+Everything goes through `make` (run `make` alone for the target list). Each target
+installs only the PEP 735 dependency group it needs into a single `.venv` and stamps it
+in `.venv/.stamps/`, so re-runs are free.
+
+```bash
+make deps          # install the `dev` group + editable install
+make format        # isort + black (write)
+make cs            # isort/black --check + flake8
+make ann           # mypy
+make test          # tox: full suite under coverage on py313 and py314
+make check         # everything the `ci` workflow runs, same targets
+make doc           # sphinx-apidoc into docs/modules/ then sphinx-build into docs/build/
+```
+
+Narrower test runs (the suite is stdlib `unittest`, no pytest):
+
+```bash
+make test PY_ENV=py313
+```
+
+```bash
+.venv/bin/python -m unittest tests.operations.test_build_bootstrap.DefaultBuildBootstrapOperationTestCase.test_run
+```
+
+`tox` exists *only* to run the suite across interpreters (`py313`, `py314`); every other
+task lives in the `Makefile`. ... and leCoverage has `fail_under = 95`.
+
+Line length differs by tool on purpose: black formats at 80, flake8 allows 88.
+
+## Changelog fragments are mandatory
+
+Every PR must add one file to `changelog.d/` named `<issue>.<type>.md`, or `+<slug>.<type>.md`
+when there is no issue number (types: `added`/`changed`/`deprecated`/`removed`/`fixed`/`security`).
+CI enforces this; `make cl-check` mirrors it. Version numbers come from `setuptools-scm`
+tags, never from a file. Releases: `make release VERSION=X.Y.Z` publishes to the real
+PyPI — pass `PYPI=testpypi` to rehearse; it refuses to run on a dirty tree.
+
+## Architecture
+
+`docs/concepts/architecture.md` is the canonical description and is kept current — read it
+before making structural changes. The essentials:
+
+**Operation objects, not functions.** Every unit of work is a `BaseOperation` subclass with
+a `run()`. CLI-facing ones (`BaseCliOperation`) additionally have a *classmethod*
+`prepare_cli_parser(parser, prefix)` that registers argparse arguments, and receive their
+parsed `Namespace` via `set_cli_namespace()`. Construction takes no arguments — collaborators
+are injected through `set_*` methods before `run()`. Follow this shape for new operations.
+
+**Two-phase CLI.** `py_bootstrap/scripts/bootstrap.py` builds the parser tree by walking
+operation classes, then dispatches at `run()` time by reading the subcommand out of the
+namespace. Because `build`/`export` add one sub-parser per discovered bootstrap, *building
+the parser already imports every bootstrap's `__entry_point__`* — parser construction must
+stay side-effect free. `build_parser()` in that module is the hook `sphinx-argparse` uses to
+render `docs/reference/cli.md`.
+
+**Discovery via entry points.** Bootstraps are found through the `py_bootstrap_templates`
+setuptools entry-point group (`BaseBootstrapsOperation.find_bootstraps()`). Each contributing
+package points at a `...py_bootstrap.templates` module exposing `ENABLED_TEMPLATES` — a list
+of subdirectory names, each of which must contain `__entry_point__.py`. This project registers
+its own built-ins the same way (`py_bootstrap/templates/__init__.py`), so built-in, registered
+and third-party plugin bootstraps are indistinguishable to the tool. Import failures during
+discovery are logged and skipped, never raised.
+
+**A bootstrap's `__entry_point__.py`** must define module-level `DESCRIPTION` plus
+`BuildOperation` and `ExportOperation` classes — `register` validates by string-searching the
+file for those two names. Subclass `DefaultBuildBootstrapOperation` to get the standard
+`--name`/`--description` options and the derived `python_name`/`upper_name`/`class_name`/`title`
+placeholders; subclass `BaseBuildBootstrapOperation` directly for something bespoke. Override
+`build_context()` and always `super()` into it.
+
+**Files processors** (`py_bootstrap/files_processors/`) do the actual walking and writing.
+`CopyFilesProcessor` copies verbatim (used by `export` and `register`);
+`GenerateFilesProcessor` subclasses it and adds templating (used by `build`).
+
+### Templating rules (easy to get wrong)
+
+- Rendering is plain `str.format(**context)` — the context is a flat `str -> str` map. Literal
+  braces in template content must be doubled.
+- **Destination paths are rendered too**, not just file content. Hence a directory named
+  `{python_name}/` in a bootstrap becomes a directory named after the project.
+- A file is templated only if it ends in `.tmpl`; the suffix is stripped on output. To emit a
+  file that itself ends in `.tmpl`, name it `*.tmpl.tmpl` (see `templates/bootstrap/`).
+- `{empty}` renders to `""` and exists so template files can produce dotfiles:
+  `{empty}.gitignore.tmpl` -> `.gitignore`. A bare `.gitignore` in the bootstrap dir would be
+  swallowed by this repo's own tooling.
+- `__entry_point__.py` is skipped by `build` but copied by `export`/`register`.
+
+## Tests
+
+`tests/` mirrors the package layout. Fixtures live in two places with different roles:
+`tests/tst_templates/` is an importable package of bootstrap fixtures (including deliberately
+broken ones: `test_missed_entry_point`, `test_wrong_entry_point`), while
+`tests/tst-register-bootstrap-source/` is a non-importable directory used as a `register`
+source. Tests exercise operations by constructing them and feeding a hand-built
+`argparse.Namespace` rather than by going through the CLI; `tests/scripts/test_bootstrap.py`
+is the exception that drives `main()` end to end. Tests that write files create them under
+the CWD and clean up in `tearDown`.
+
+mypy excludes `templates/` and `tst_templates/` (they contain intentionally invalid template
+syntax) and relaxes several error codes for `tests.*`.
+
+## Notes
+
+- The `Makefile` is the source of truth for how the checks actually run.
+- `docs/modules/` and `docs/build/` are generated; never edit them by hand.