flowmark 0.7.2__tar.gz → 0.8.0__tar.gz

flowmark-0.8.0/.agents/skills/flowmark/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: flowmark
+description: Fast, consistent Markdown auto-formatter for typographic cleanup, normalization, and clean semantic line breaks. Use when creating, editing, or cleaning Markdown; formatting LLM-generated docs; adopting Flowmark in a repository; adding Markdown format scripts or commit hooks; or replacing Prettier or another Markdown formatter.
+allowed-tools: Bash(flowmark:*), Bash(uvx:*), Read, Write
+---
+<!-- DO NOT EDIT: `flowmark --install-skill` (format=f03 surface=skill-md) -->
+
+# Flowmark - Markdown Auto-Formatter
+
+Fast, consistent Markdown auto-formatter.
+Run it on Markdown you generate or edit so committed diffs stay small and readable.
+It is conservative and safe to run on every file: it never modifies code blocks or
+inline code.
+
+## Format Markdown
+
+Format in place with all auto-formatting (typography, cleanups, semantic line breaks):
+
+```bash
+flowmark --auto FILE   # one file
+flowmark --auto .      # whole tree (respects .gitignore and .flowmarkignore)
+```
+
+Omit `--auto` to preview to stdout; pipe stdin with `-` (e.g. `cat FILE | flowmark -`).
+
+Use `flowmark` when it is already on `PATH`. Otherwise use the fast
+[Rust port](https://github.com/jlevy/flowmark-rs) with a version-pinned `uvx` runner
+(never `@latest`):
+
+```bash
+uvx --from flowmark-rs==0.4.0 flowmark --auto FILE
+```
+
+The [Python reference](https://github.com/jlevy/flowmark) remains available when its
+library API or a newer unported patch is required:
+
+```bash
+uvx --from flowmark==0.8.0 flowmark --auto FILE
+```
+
+## Adopt Flowmark in a Repository
+
+If this skill came from `flowmark --skill`, run the same runner with `--install-skill`
+from the project root to materialize the complete bundle.
+Then, for a repository-wide migration, Makefile wiring, `.flowmarkignore`, commit hooks,
+CI policy, and disabling Prettier or other competing Markdown formatters, read
+[project-setup.md](references/project-setup.md) in full before editing.
+
+## Full Documentation
+
+Flowmark documents itself.
+Use the CLI rather than reproducing details here:
+
+- `flowmark --help` — every flag: `--semantic`, `--smartquotes`, `--ellipses`,
+  `--width`, `--check`, list spacing, and file discovery
+  (`--extend-include`/`--extend-exclude`).
+- `flowmark --docs` — the full guide: configuration, file discovery, editor setup, the
+  Python library API, and installing this skill (`flowmark --install-skill`).
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

flowmark-0.8.0/.agents/skills/flowmark/references/project-setup.md

@@ -0,0 +1,111 @@
+<!-- DO NOT EDIT: `flowmark --install-skill` (format=f03 surface=skill-reference) -->
+
+# Project Setup and Migration
+
+Use this workflow when adopting Flowmark across a repository.
+Keep one `flowmark` skill; project setup is a use case of that skill, not a separate
+skill.
+
+## Migration Checklist
+
+1. Find the Markdown sources and identify generated, vendored, fixture, and golden files
+   that must retain byte-exact content.
+2. Add those paths to `.flowmarkignore`.
+3. Make Flowmark the only formatter that owns Markdown.
+   Disable Markdown in Prettier, Biome, dprint, editor format-on-save settings, and
+   existing Markdown hooks.
+4. Add one pinned project command and run it once over the repository.
+   Review and commit the baseline reformat separately from content changes.
+5. Add an auto-fixing commit hook.
+   Prefer a hook that stages its fixes so formatting does not become a manual gate.
+6. Do not fail the main build only for ordinary Markdown formatting drift.
+   Keep formatting local and automatic; reserve CI drift checks for generated or
+   contractually byte-exact documentation.
+
+## Pinned Project Command
+
+Prefer the Rust port through `uvx`:
+
+```makefile
+FLOWMARK := uvx --from flowmark-rs==0.4.0 flowmark
+
+.PHONY: format-docs
+format-docs:
+	$(FLOWMARK) --auto .
+```
+
+Passing `.` lets Flowmark discover files once and honor `.gitignore` and
+`.flowmarkignore` from the repository root.
+Avoid shell `find` pipelines or per-directory invocations unless the repository requires
+them.
+
+Start `.flowmarkignore` with content Flowmark must not rewrite:
+
+```gitignore
+# Generated or vendored Markdown
+docs/api/_generated/
+third_party/
+
+# Byte-exact fixtures and golden files
+tests/fixtures/
+tests/golden/
+```
+
+When documentation is generated, format canonical sources first, then regenerate their
+mirrors. Exclude generated mirrors from Flowmark so there is one source of truth.
+
+## Auto-Fix on Commit
+
+Lefthook can format and stage Markdown without turning style into a separate failure:
+
+```yaml
+pre-commit:
+  commands:
+    flowmark:
+      glob: "*.{md,mdc,markdown}"
+      run: uvx --from flowmark-rs==0.4.0 flowmark --auto --force-exclude {staged_files}
+      stage_fixed: true
+```
+
+`--force-exclude` applies `.flowmarkignore` even though the hook passes explicit file
+paths. If generated docs must be refreshed after formatting, call one repository script
+or Make target that performs both operations in the required order.
+
+For the `pre-commit` framework, use a local system hook with the same pinned command:
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: flowmark
+        name: flowmark
+        entry: uvx --from flowmark-rs==0.4.0 flowmark --auto --force-exclude
+        language: system
+        files: '\.(md|mdc|markdown)$'
+```
+
+Keep both hook selectors aligned with any Markdown extensions the repository discovers
+through `--extend-include`. The `pre-commit` framework stops the first commit after
+modifying files; stage the fixes and retry.
+Use Lefthook with `stage_fixed: true` when transparent auto-staging is preferred.
+
+## Disable Competing Markdown Formatters
+
+For Prettier, exclude Markdown in `.prettierignore`:
+
+```gitignore
+*.md
+```
+
+Also remove Markdown-specific Prettier hooks and editor defaults.
+If Flowmark owns MDX or another extension via `--extend-include`, exclude that extension
+from Prettier too.
+
+Apply the same ownership rule to other tools: keep them for code and data formats, but
+remove Markdown from their include globs and format-on-save configuration.
+Do not run two Markdown formatters sequentially; they can churn each other’s output and
+make hooks or CI nondeterministic.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

flowmark-0.8.0/.agents/skills/simple-modern-uv/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: simple-modern-uv
+description: >-
+  Set up, modernize, or update Python projects using the simple-modern-uv template:
+  uv, ruff, BasedPyright, pytest, GitHub Actions CI, and tag-driven PyPI publishing.
+  Use when starting a new Python project or package; when modernizing, upgrading, or
+  migrating an existing Python package to uv (from Poetry, setuptools, pip,
+  requirements.txt, or PDM); or when updating a project already built from
+  simple-modern-uv to the latest template.
+license: MIT
+compatibility: Requires git and uv (https://docs.astral.sh/uv/); network access to GitHub
+metadata:
+  author: jlevy (github.com/jlevy)
+  source: https://github.com/jlevy/simple-modern-uv
+allowed-tools: Bash(uvx:*), Bash(uv:*), Bash(git:*), Bash(make:*), Bash(gh:*), Read, Write, Edit
+---
+# simple-modern-uv: Modern Python Project Setup
+
+[simple-modern-uv](https://github.com/jlevy/simple-modern-uv) is a minimal, modern
+Python project template: **uv** for everything package-related, **ruff** for
+lint/format, **BasedPyright** for type checking, **pytest**, GitHub Actions CI, and
+tag-driven publishing to PyPI with dynamic versioning (the git tag is the version).
+It is a [Copier](https://copier.readthedocs.io) template, so projects can pull future
+template improvements at any time with `copier update`.
+
+There are three workflows.
+Pick by situation:
+
+1. **New project**: create a project from scratch.
+2. **Upgrade existing project**: convert any existing Python package to this template’s
+   structure and tooling.
+   See [references/adopt-existing.md](references/adopt-existing.md).
+3. **Update templated project**: the project has a `.copier-answers.yml` from this
+   template; pull the latest template changes.
+
+For all workflows: when something fails, check [references/faq.md](references/faq.md)
+before improvising. For post-setup customization (license change, private/unpublished
+package, entry points), see [references/customize.md](references/customize.md).
+
+If this file was fetched from a URL rather than installed as a folder, fetch the
+reference files from the **same ref**: replace `SKILL.md` in the URL you used with
+`references/<name>.md` (don’t mix a pinned `SKILL.md` with references from `main`).
+
+## The Interview: What to Ask the User (and What Not to Ask)
+
+Every workflow uses the same answer set (the template’s questions in
+[copier.yml](https://github.com/jlevy/simple-modern-uv/blob/main/copier.yml)). **Infer
+everything you can, then ask the user to confirm once, in a single batched message.**
+Never ask one question at a time, and never ask about things listed under “conventions”
+below.
+
+**Essentials** (confirm these; they are the user’s decisions):
+
+| Answer key | Meaning | Notes |
+| --- | --- | --- |
+| `package_name` | PyPI package and GitHub repo name | Normalize to **kebab-case** (`acme-widgets`); show the user the name you derived |
+| `package_module` | Python module name | Derived automatically as **snake_case** (`acme_widgets`); show it, don’t ask |
+| `package_description` | One-line description |  |
+| `package_license` | `MIT` (default), `Apache-2.0`, `BSD-3-Clause`, `AGPL-3.0-or-later`, `Proprietary`, or `None` (decide later) | Always surface, naming the default |
+| `publish_to_pypi` | `true` (default) or `false` | Always surface; `false` for private packages and apps |
+
+For `package_author_name`, `package_author_email`, and `package_github_org`, **infer**
+values from `git config user.name` and `user.email` and the repo’s remote or
+`gh auth status`, and include them in the confirmation summary rather than asking.
+
+**Conventions** (apply silently; mention in your final summary; deviate only if the user
+explicitly asks): `src/` layout; first version is the git tag `v0.1.0` for a new project
+(for upgrades of published packages, the next version above what’s on PyPI); Python
+3.11+; line length 100; the template’s tool choices.
+These are never questions.
+
+## Workflow 1: New Project
+
+1. Run the interview (above).
+   Then render, replacing the answer values:
+
+   ```bash
+   uvx --exclude-newer "14 days" copier@9.16.0 copy --defaults \
+     --data package_name=acme-widgets \
+     --data "package_description=One-line description" \
+     --data "package_author_name=Jane Doe" \
+     --data package_author_email=jane@example.com \
+     --data package_github_org=acme \
+     --data package_license=MIT \
+     --data publish_to_pypi=true \
+     gh:jlevy/simple-modern-uv acme-widgets
+   ```
+
+   (Omit `--data` keys that should take defaults.
+   `package_module` derives automatically from `package_name`.)
+
+2. Initialize git, commit, then install.
+   Sync only after the first commit: dynamic versioning reads git, and syncing first
+   leaves the editable install’s version at `0.0.0`.
+
+   ```bash
+   cd acme-widgets
+   git init --initial-branch=main
+   git add . && git commit -m "Initial commit from simple-modern-uv."
+   make install
+   git add uv.lock && git commit -m "Add uv.lock."
+   ```
+
+3. **Verify**: `make lint` and `make test` must pass.
+   Fix anything that doesn’t before declaring success.
+
+4. Offer next steps (don’t just stop): create the GitHub repo and push (an empty repo
+   with no README, license, or .gitignore; the template provides them); fill in
+   `README.md`; if publishing, `docs/publishing.md` covers the one-time PyPI Trusted
+   Publisher setup; tag `v0.1.0` when ready to release.
+
+## Workflow 2: Upgrade an Existing Project
+
+Follow [references/adopt-existing.md](references/adopt-existing.md).
+In brief: run the interview with answers **inferred from the repo itself**
+(pyproject/setup.py metadata, LICENSE file, git remote, PyPI presence), render the
+template into a sibling temp directory with those answers, merge the template’s
+structure into the project (preserving its dependencies, metadata, and code), translate
+old tool configs to uv equivalents, write `.copier-answers.yml` so future updates work,
+and verify with `make install`, lint, and tests.
+Land everything on a branch as one reviewable change.
+
+## Workflow 3: Update a Templated Project
+
+Requires a clean working tree and the project’s `.copier-answers.yml`.
+
+1. If the template has questions the project has never answered (keys present in the
+   template’s `copier.yml` but missing from the project’s `.copier-answers.yml`), first
+   check the project’s actual state and pass matching `--data` so defaults can’t revert
+   hand customizations (see “Reconciling New Questions on Update” in
+   [references/customize.md](references/customize.md)).
+
+2. ```bash
+   uvx --exclude-newer "14 days" copier@9.16.0 update --defaults --skip-answered
+   ```
+
+3. Resolve any `*.rej` files or inline conflict markers, re-run `make lint` and
+   `make test`, then summarize what the template update changed (check the
+   [release notes](https://github.com/jlevy/simple-modern-uv/releases)).
+
+## Verification Gate (All Workflows)
+
+Before reporting success: `make install`, `make lint`, and `make test` all pass, and for
+publishable packages `make build` produces a wheel with a sensible version (requires at
+least one git commit; see the FAQ if the version looks wrong).
+Report what you ran and the results.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

flowmark-0.8.0/.agents/skills/simple-modern-uv/references/adopt-existing.md

@@ -0,0 +1,135 @@
+# Upgrading an Existing Project to simple-modern-uv
+
+Convert an existing Python package (setuptools/pip, Poetry, PDM, hatch, or plain
+scripts) to the simple-modern-uv structure.
+The approach: render the template next to the project, then merge it in deliberately;
+never blindly overwrite.
+Work on a branch and land the whole migration as one reviewable change.
+
+Out of scope (stop and tell the user): C extensions or custom build steps, conda
+environments, monorepos/workspaces with multiple packages.
+These need decisions a checklist shouldn’t make.
+
+## Step 1: Infer the Interview Answers from the Repo
+
+| Answer | Where to look |
+| --- | --- |
+| `package_name` | `[project] name`, `setup.py name=`, `[tool.poetry] name`, or the repo name |
+| `package_description` | `[project] description` or `setup.py description=` |
+| `package_author_name` / `email` | `[project] authors`, `[tool.poetry] authors`, or git log |
+| `package_github_org` | `git remote get-url origin` |
+| `package_license` | `LICENSE` file contents and `license` field/classifiers; map to MIT, Apache-2.0, BSD-3-Clause, or AGPL-3.0-or-later; no license found maps to None; else Proprietary |
+| `publish_to_pypi` | `true` if the package is on PyPI (`uv pip index` or check pypi.org) or clearly intended for it; `false` for apps/private code (a `Private :: Do Not Upload` classifier is a definitive no) |
+
+Confirm the essentials with the user in one batched message (per the interview contract
+in SKILL.md), flagging anything that will change.
+One decision that must be surfaced if it applies: if the project currently supports
+Python older than 3.11 **and** is published, adopting the template raises
+`requires-python` to `>=3.11`. Dropping versions for existing users is the user’s call,
+not yours.
+
+## Step 2: Render the Template Beside the Project
+
+```bash
+cd ..
+uvx --exclude-newer "14 days" copier@9.16.0 copy --defaults \
+  --data package_name=<name> ... \
+  gh:jlevy/simple-modern-uv <project>-template-render
+```
+
+Use the render as the source of truth for structure; you will copy from it into the real
+project.
+
+## Step 3: Merge Structure into the Project
+
+Copy from the render, adapting as you go:
+
+- **`pyproject.toml`**: start from the rendered one and port the project’s reality into
+  it: `dependencies`, extras, entry points, tool configs that should survive (translate
+  as below). Keep the rendered `[build-system]` (hatchling with uv-dynamic-versioning),
+  `[tool.uv]`, `[tool.ruff]`, `[tool.basedpyright]`, `[tool.pytest.ini_options]`
+  sections.
+- **Code layout**: move code to `src/<module>/` (the convention; if the user insists on
+  a flat layout, adjust `packages` and `testpaths` instead).
+  Ensure `py.typed` exists in the package.
+  Tests go in `tests/`.
+- **Copy verbatim**: `devtools/lint.py`, `Makefile`, `.gitignore` (merge with existing
+  entries), `.github/workflows/ci.yml` (and `publish.yml` if publishing),
+  `docs/installation.md`, `docs/development.md`.
+- **Agent instruction files**: copy `AGENTS.md` and `CLAUDE.md` from the render if the
+  project has neither.
+  If the project already has an `AGENTS.md`, keep its content and fold in the template’s
+  build/test commands.
+  If it already has a `CLAUDE.md`, don’t overwrite it; add the `@AGENTS.md` import line
+  at the top so Claude Code picks up the shared conventions.
+- **`.copier-answers.yml`**: copy from the render.
+  This is what makes future `copier update` work; without it the project is orphaned
+  from the template.
+- **Delete superseded files** (after their content is ported): `setup.py`, `setup.cfg`,
+  `requirements*.txt`, `poetry.lock`, `pdm.lock`, `Pipfile*`, old
+  `tox.ini`/`.flake8`/`mypy.ini`/`.pylintrc`, old CI workflows that the template’s CI
+  replaces.
+
+## Per-Source Translations
+
+**Poetry**:
+
+- Caret/tilde specs → PEP 621 ranges: `^1.2.3` → `>=1.2.3,<2.0.0`; `~1.2.3` →
+  `>=1.2.3,<1.3.0`. Prefer simple `>=` floors where the project doesn’t actually need
+  upper bounds.
+- `[tool.poetry.dependencies]` → `[project] dependencies` (drop the `python` entry;
+  that’s `requires-python`).
+- `[tool.poetry.group.dev.dependencies]` (or `dev-dependencies`) →
+  `[dependency-groups] dev`.
+- `[tool.poetry.scripts]` → `[project.scripts]`.
+- `[tool.poetry] version` → delete; the version now comes from git tags
+  (`dynamic = ["version"]`).
+- `packages = [{include = "pkg", from = "src"}]` → hatch’s
+  `[tool.hatch.build.targets.wheel] packages = ["src/pkg"]` (already in the rendered
+  file).
+
+**setuptools/pip**:
+
+- `setup.py`/`setup.cfg` metadata → `[project]` table.
+  `install_requires` → `dependencies`; `extras_require` →
+  `[project.optional-dependencies]`; `entry_points["console_scripts"]` →
+  `[project.scripts]`.
+- `requirements.txt` → runtime deps to `dependencies`; `requirements-dev.txt` →
+  `[dependency-groups] dev`. Drop exact `==` pins unless genuinely required; `uv.lock`
+  provides reproducibility.
+
+**mypy → BasedPyright**: drop `mypy.ini`/`[tool.mypy]`; the rendered
+`[tool.basedpyright]` block is the starting point.
+Existing `# type: ignore` comments still work.
+If legacy code produces a wall of errors, see the FAQ: relax first, ratchet later.
+
+**Other linters (flake8, isort, black, pylint)**: delete their configs; ruff covers them
+(`I` rules replace isort, the formatter replaces black).
+
+## Step 4: Lock, Verify, Iterate
+
+```bash
+make install               # creates uv.lock; commit it
+make lint                  # codespell + ruff + basedpyright
+make test
+make build                 # only if publishing
+```
+
+Fix failures using [faq.md](faq.md).
+Lint/type errors in legacy code are normal on first run: auto-fix what `make lint`
+fixes, relax basedpyright rules where the noise is unhelpful (leave a comment), and
+don’t rewrite working code just to satisfy a rule.
+
+## Step 5: Versioning and Finish
+
+- Dynamic versioning needs a tag: if the package is on PyPI at version X.Y.Z, tag the
+  merge commit `vX.Y.(Z+1)` (or the next minor) **after** merging; an unpublished
+  project starts at `v0.1.0`. Until a tag exists, builds get a dev version: fine for CI,
+  wrong for release.
+- Commit everything (including `uv.lock` and `.copier-answers.yml`) on the branch and
+  summarize: what moved, what was translated, what was deleted, anything the user should
+  review by hand (license, classifiers, CI triggers).
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

flowmark-0.8.0/.agents/skills/simple-modern-uv/references/customize.md

@@ -0,0 +1,75 @@
+# Customizing a simple-modern-uv Project
+
+Common customizations after (or during) setup.
+Where a customization maps to a template question, prefer answering the question over
+hand-editing: hand edits to template-managed files can be reverted by a later
+`copier update` (see “Reconciling New Questions on Update” below).
+
+## Changing the License
+
+Preferred: set the `package_license` answer (`MIT`, `Apache-2.0`, `BSD-3-Clause`,
+`AGPL-3.0-or-later`, `Proprietary`, or `None` to decide later) when rendering, or
+re-answer it later with:
+
+```bash
+uvx --exclude-newer "14 days" copier@9.16.0 update --data package_license=Apache-2.0
+```
+
+This updates the `LICENSE` file and the `license` field in `pyproject.toml` together,
+and records the answer in `.copier-answers.yml`. `None` renders no `LICENSE` file and no
+`license` field; re-answer the question when the project picks one.
+For a license outside the template’s choices: pick `Proprietary` (so the template stops
+managing it), then replace `LICENSE` and set `license` in `pyproject.toml` to the
+correct SPDX identifier yourself.
+
+## Private or Unpublished Packages
+
+Set `publish_to_pypi=false` (at render time, or via
+`copier update --data publish_to_pypi=false`). This removes
+`.github/workflows/publish.yml` and `docs/publishing.md`, and adds the
+`Private :: Do Not Upload` classifier so PyPI rejects an accidental upload.
+Everything else (CI, lint, tests, versioning) keeps working.
+To start publishing later, flip the answer back the same way, then do the one-time
+Trusted Publisher setup in `docs/publishing.md`.
+
+## Reconciling New Questions on Update
+
+When the template adds questions over time, a project that predates them has no recorded
+answer, and `copier update --defaults` fills in the default, which can contradict hand
+edits made before the question existed.
+Before updating an older project, check its actual state and pass explicit `--data`:
+
+- Hand-replaced license?
+  Pass the matching `package_license` (or `Proprietary` for anything custom).
+- Deleted `publish.yml` by hand, or has the `Private :: Do Not Upload` classifier?
+  Pass `publish_to_pypi=false`.
+
+Rule of thumb: defaults describe a fresh project, not yours; anywhere the project
+visibly deviates from a fresh render, make the answer explicit.
+
+## Apps and CLIs (vs. Libraries)
+
+- Entry points live in `[project.scripts]`: `mycli = "my_module.cli:main"`; then
+  `uv run mycli` works and installs expose the command.
+- An app that’s not a library usually wants `publish_to_pypi=false`; it still gets the
+  full dev workflow.
+- For a long-lived service, consider pinning the Python version with a `.python-version`
+  file (uv reads it automatically).
+
+## Other Common Tweaks
+
+- **Line length**: `[tool.ruff] line-length` in `pyproject.toml` (default 100; black
+  uses 88).
+- **Stricter/looser type checking**: toggle the commented `report*` settings in
+  `[tool.basedpyright]`; the template ships a pragmatic middle ground.
+- **More ruff rules**: uncomment entries in `[tool.ruff.lint] select` (e.g. `"D"` for
+  docstring rules, `"SIM"` for simplifications).
+- **OS matrix in CI**: edit `os:` in `.github/workflows/ci.yml`
+  (`["ubuntu-latest", "macos-latest", "windows-latest"]`).
+- **Spell-check exceptions**: `[tool.codespell] ignore-words-list`.
+
+After any customization, re-run `make lint` and `make test`.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

flowmark-0.8.0/.agents/skills/simple-modern-uv/references/faq.md

@@ -0,0 +1,89 @@
+# FAQ: Common Problems
+
+Failure modes seen in real setups and migrations, with fixes.
+Check here before improvising.
+
+## Build Fails: “This does not appear to be a Git project”
+
+`uv-dynamic-versioning` reads the version from git.
+The project must be a git repo with at least one commit before `uv build` (or any
+build-backend invocation, including the editable install during `uv sync`) can resolve a
+version. Fix:
+`git init --initial-branch=main && git add . && git commit -m "Initial commit"`.
+
+## Version Is 0.0.0, 0.1.devN, or Otherwise Wrong
+
+No git tag yet: dynamic versioning derives the version from the latest `v*` tag.
+
+- New project: tag `v0.1.0` when ready to release; dev versions before that are normal
+  and harmless for CI.
+- Migrated package already on PyPI at X.Y.Z: the first tag must be **greater** than
+  X.Y.Z (e.g. `vX.Y.(Z+1)`), or the publish will be rejected as a duplicate/downgrade.
+- Tag exists but ignored: tags must look like `v1.2.3`; also check CI uses
+  `fetch-depth: 0` (the template’s workflows do) so tags are available.
+- `importlib.metadata` still reports an old version after committing or tagging: the
+  editable install’s metadata is captured at sync time and uv won’t refresh it on its
+  own. Run `uv sync --reinstall-package <module>` (and sync only after the first commit
+  on new projects).
+
+## `uv sync` Fails on Python Version
+
+The template requires Python 3.11+. `uv python install` downloads a managed interpreter;
+pin one for the project with `uv python pin 3.12` (writes `.python-version`). If uv
+itself errors with “required-version”, upgrade uv: the template requires uv >= 0.9.
+
+## BasedPyright Erupts with Hundreds of Errors on Legacy Code
+
+Expected on first run over older code.
+Don’t rewrite the codebase to satisfy it, and don’t turn it off:
+
+1. Start from the template’s `[tool.basedpyright]` block, which already relaxes the
+   noisiest rules.
+2. Temporarily disable the loudest remaining categories (uncomment the provided
+   `report*` lines, e.g. `reportUnknownVariableType = false`), leaving a comment to
+   ratchet later.
+3. Existing mypy-style `# type: ignore` comments still work; prefer fixing real findings
+   over suppressing them.
+
+## codespell Flags Names or Legacy Prose
+
+Add exceptions in `pyproject.toml`: `[tool.codespell] ignore-words-list = "word1,word2"`
+or `skip = "path1,path2"`.
+
+## Conflicts During `copier update`
+
+Copier writes `*.rej` files (or inline conflict markers) where the template and local
+edits collide. Resolve each by hand, keeping the project’s intent; delete the `.rej`
+files; re-run `make lint` and `make test`. A dirty working tree also blocks updates;
+commit or stash first.
+
+## `publish.yml` Came Back or License Reverted After an Update
+
+The project predates the `publish_to_pypi` and `package_license` questions and the
+update filled them with defaults.
+Re-run the update passing the project’s reality, e.g.
+`uvx --exclude-newer "14 days" copier@9.16.0 update --data publish_to_pypi=false`, and
+see “Reconciling New Questions on Update” in [customize.md](customize.md).
+
+## Publish Workflow Fails with OIDC or Permission Errors
+
+The one-time PyPI Trusted Publisher setup hasn’t been done for this repo (or the
+workflow filename doesn’t match what PyPI was told).
+Follow `docs/publishing.md` in the project; no API tokens are needed.
+
+## Lockfile Resolution Seems Stale or Refuses a Brand-New Release
+
+`UV_EXCLUDE_NEWER` (set in the template’s CI) enforces a 14-day supply-chain cooling-off
+window, so releases newer than that are deliberately invisible.
+This is a feature; don’t remove it to get a day-old package.
+Locally, leave the variable unset for normal work, or set it to match CI when debugging
+resolution differences.
+
+## Tests Pass Locally but CI Fails on a Python Version
+
+The CI matrix runs 3.11–3.14. Most failures are version-specific syntax/stdlib use; run
+the failing version locally with `uv run --python 3.11 pytest`.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->