readwright 0.3.0__tar.gz → 0.5.0__tar.gz

readwright-0.5.0/.agents/skills/readwright/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: readwright
+description: Use when creating or editing a project's README.md that is managed by readwright — writing/extending README.md.j2, configuring readme.yaml or [tool.readme], adding badges/screenshots/TOC/changelog sections, or a "readwright check" / pre-commit readwright-check failure shows README.md is stale or was hand-edited.
+---
+
+# readwright
+
+## Overview
+
+readwright renders `README.md` from a Jinja2 template (`README.md.j2`) plus a config
+file (`readme.yaml` or `[tool.readme]` in `pyproject.toml`). `README.md` carries a
+`<!-- generated by readwright -->` marker and is **never hand-edited** — edit the
+template/config, then re-render.
+
+## Workflow
+
+1. New project: `readwright init` (autodetects owner/repo/name/license from git
+   remote + manifest files). Existing README to preserve: `readwright init
+   --from-readme`. Prefer config in `pyproject.toml`: `readwright init --pyproject`.
+2. Edit `README.md.j2` — it extends the packaged `base.md.j2` and overrides only the
+   `{% block %}` sections it needs — and/or `readme.yaml`.
+3. `readwright render` to write `README.md` (`--watch` to re-render on save, `-o -`
+   to preview on stdout instead of writing).
+4. `readwright check` before committing — exits 1 with a diff if `README.md` is
+   stale versus what the template+config would produce. This is what CI / the
+   `readwright-check` pre-commit hook run; if it fails, run `render` again, don't
+   hand-patch `README.md`.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `readwright init [--from-readme] [--pyproject]` | Scaffold `readme.yaml` + `README.md.j2` |
+| `readwright render [--watch] [-o -] [--user-config]` | Write `README.md` |
+| `readwright check` | Fail with a diff if `README.md` is stale (CI/pre-commit) |
+| `readwright badges` | List available badge presets |
+| `readwright blocks` | List overridable template blocks/partials |
+| `readwright skill [--install] [--dest DIR] [--force]` | Print the bundled copy of this skill, or install it into a project's `.agents/skills/` (or `--dest`) |
+| `readwright show <template>` | Print a packaged template (`base.md.j2` for the block order, or e.g. `partials/install.md.j2`) to copy and customize |
+| `readwright completion <shell>` | Print a bash/zsh/fish/PowerShell completion script |
+
+All accept `-C/--root` (repo root) and `-c/--config` (explicit config path) as
+options *after* the subcommand, e.g. `readwright render -C /path/to/repo` —
+`readwright -C /path render` fails with "No such option: -C".
+
+## Template helpers
+
+Full reference with examples: [helpers.md](helpers.md). Quick index:
+
+| Helper | Purpose |
+| --- | --- |
+| `badge()`, `shield()`, `badges()`, `donate_badges()` | Badges from presets, custom shields.io badges, or config-driven rows |
+| `screenshot()`, `screenshots()`, `image()`, `logo()`, `video()`, `unsplash()` | Images: single shot, gallery, explicit image, theme-aware logo, video/gif, Unsplash hero |
+| `toc()` | Table of contents from headings below the call |
+| `changelog()` | Latest N entries from `CHANGELOG.md` |
+| `cli_help()` | Runs a command and fences its `--help` output (needs `allow_exec: true`) |
+| `include_file()`, `code_block()`, `snippet()` | Pull in a file, a fenced file, or a marked region |
+| `config_table()`, `env_table()`, `entry_points_table()` | Tables from YAML/TOML/JSON, `.env` files, `[project.scripts]` |
+| `gh_link()`, `spdx_link()`, `my_ha_link()` | Repo-relative GitHub links, SPDX license link, My Home Assistant buttons |
+| `callout()`, `details()`, `center()`, `columns()` | GitHub alerts, collapsibles, centered blocks, side-by-side layout |
+| `contributors()` | Avatar grid |
+| `flow_install_cmd()`, `mc_versions()`, `mod_dependencies()`, `related_repos()` | Flow Launcher / Minecraft mod / related-repo tables |
+| `git_sha()`, `git_tag()`, `today()` | Build metadata — these change between renders, so `check` will flag a README rendered with them as stale until re-rendered at release/CI time |
+| `project.*`, `vars.*` | Autodetected repo metadata and free-form config values |
+
+Image helpers emit plain markdown by default; pass `width=`, `html=True`, or set
+`screenshots.style: html` to get `<img>`/`<picture>`/`<table>` output instead.
+
+## Overriding blocks and partials
+
+`base.md.j2` blocks: `header`, `badges`, `donate`, `toc`, `screenshots`, `install`,
+`usage`, `extra`, `contributing`, `license`. Override any block in `README.md.j2`:
+
+```jinja
+{% extends "base.md.j2" %}
+{% block usage %}
+## Usage
+{{ screenshot("main", width=600) }}
+Run `{{ project.name }} --help`.
+{% endblock %}
+```
+
+Add to the top badge row without touching the config list via the `badges_extra` /
+`donate_extra` hooks. Any packaged partial can be shadowed by a same-named file
+under `templates/partials/` in the repo (or `~/.config/readwright/templates/` for
+all repos) — `readwright show <partial>` prints the original to copy.
+
+To insert a whole new section where there's no dedicated hook (e.g. a Changelog
+section between Contributing and License — there's no `contributing_extra` block),
+override the nearest existing block and call `{{ super() }}` to keep its content,
+then append (or prepend) yours:
+
+```jinja
+{% block contributing %}
+{{ super() }}
+
+## Changelog
+
+{{ changelog(2) }}
+{% endblock %}
+```
+
+## Configuration (`readme.yaml`)
+
+```yaml
+template: README.md.j2
+templates: [../shared-readme-templates, "pkg:my_org_templates"]  # extra search paths
+output: README.md
+strict: false                # missing screenshot -> error, not warning
+allow_exec: false             # let cli_help() run commands during render
+badges_style: flat-square     # shields.io style for every badge
+related: [{repo: other-tool, description: Sibling project}]
+banner: {unsplash: photo-1518770660439-4636190af475, credit: Name, user: handle}
+screenshots: {dir: docs/screenshots, width: 720, style: markdown}
+badges: [pypi, python, license, {preset: ci, workflow: test.yml}, {shield: {label: Docs, message: latest, color: success}}]
+badges_custom:
+  discord: {label: Discord, message: chat, color: 5865F2, link: https://discord.gg/xyz}
+donate: [kofi, github-sponsors]
+donate_handles: {kofi: yourname, github-sponsors: yourname}
+project: {name: ..., owner: ..., repo: ..., tagline: ..., pypi: ..., npm: ..., license: ..., ci_workflow: ...}
+vars: {anything: you like}
+```
+
+Metadata not set explicitly is autodetected from the git remote, `LICENSE`, and
+whichever manifest exists (`pyproject.toml`, `package.json`, `Cargo.toml`, `go.mod`,
+`*.csproj`, Gradle `gradle.properties`, `hacs.json`, Flow Launcher `plugin.json`) —
+the install section adapts to the detected project type. Shared values (donation
+handles, owner, custom badges) go in `~/.config/readwright/config.yaml`; `init`
+bakes them into the new `readme.yaml`, or merge them ad hoc with `render
+--user-config`.
+
+## Screenshots
+
+Drop images in `docs/screenshots/` (or the configured `screenshots.dir`).
+`screenshot("main")` finds `main.{png,jpg,gif,webp,svg}`; a `main-dark.*` +
+`main-light.*` pair becomes a theme-aware image using GitHub's
+`#gh-light-mode-only` / `#gh-dark-mode-only` fragments. `screenshots(columns=2)`
+builds a gallery of everything in the directory; control order/captions with
+`order=[...]`, `captions={...}`, or a `captions.yaml` file in the folder.
+
+## pre-commit and CI
+
+```yaml
+# .pre-commit-config.yaml
+- repo: https://github.com/Garulf/readwright
+  rev: v0.4.0   # pin to the latest release tag
+  hooks:
+    - id: readwright-check
+```
+
+```yaml
+# .github/workflows/ci.yml
+- uses: Garulf/readwright@v0.4.0
+  with:
+    mode: check   # or render
+```
+
+## Common mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| Editing `README.md` directly | Edit `README.md.j2`/`readme.yaml`, then `readwright render` |
+| `readwright check` fails in CI only | A helper like `git_sha()`/`git_tag()`/`today()` makes output change between renders — avoid them in checked README content, or re-render right before the check |
+| `cli_help()` renders empty/errors | Set `allow_exec: true` in config — it's off by default |
+| Screenshot not picked up | Check the file lives in `screenshots.dir` (default `docs/screenshots/`) and matches the base name passed to `screenshot()` |
+| Custom badge/partial ignored | Custom badges go under `badges_custom` in config, not a template edit; custom partials go in `templates/partials/<same-name>` to shadow the packaged one |

readwright-0.5.0/.agents/skills/readwright/helpers.md

@@ -0,0 +1,130 @@
+# readwright template helpers — full reference
+
+All helpers are called from `README.md.j2` (or any partial it includes). Signatures
+below match the Python implementation; Jinja calls omit `self`.
+
+## Badges
+
+- `badge(preset, **options)` — a preset badge (`readwright badges` lists names:
+  `pypi`, `pypi-downloads`, `python`, `license`, `ci`, `codecov`, `npm`,
+  `github-release`, `github-stars`, `pre-commit`, `ruff`, `version`, `modrinth`,
+  `curseforge`, `hacs`, `ha-version`; donation presets: `kofi`, `buymeacoffee`,
+  `github-sponsors`, `patreon`, `paypal`). Presets pull from `project.*` in config —
+  e.g. `badge("ci", workflow="test.yml")` needs `project.owner`/`project.repo`.
+- `shield(label, message, color, link=None, style=None)` — a custom static
+  shields.io badge: `shield("Discord", "chat", "5865F2", link=gh_link("wiki"))`.
+- `badges()` — renders every entry in config's `badges:` list (preset names, or
+  `{preset: ..., **opts}` / `{shield: {...}}` dicts) plus anything under
+  `badges_custom:`, in one row.
+- `donate_badges()` — same, for config's `donate:` list.
+- `badges_extra` / `donate_extra` block hooks — add a badge to the row without
+  editing the config list:
+  `{% block badges_extra %} {{ shield("docs", "latest", "success") }}{% endblock %}`
+- Pass `style=` to any badge helper, or set `badges_style:` in config, to apply a
+  shields.io style (`flat-square`, etc.) to everything.
+
+## Images
+
+- `screenshot(name, alt=None, width=None)` — finds `docs/screenshots/{name}.{png,jpg,gif,webp,svg}`
+  (dir configurable via `screenshots.dir`). If `{name}-dark.*` and `{name}-light.*`
+  both exist, renders a theme-aware pair using GitHub's `#gh-light-mode-only` /
+  `#gh-dark-mode-only` markdown fragments (or an HTML `<picture>` if
+  `screenshots.style: html` / `html=True` via a wider call, or `width=` is set,
+  since markdown can't express width).
+- `screenshots(columns=2, order=None, captions=None, subdir=None)` — a gallery
+  table of every image in the screenshots dir. `order=["main", "settings"]` fixes
+  ordering; `captions={"main": "Main window"}` or a `captions.yaml` file in the
+  folder supplies captions.
+- `has_screenshots()` — boolean, for conditionally rendering a screenshots section.
+- `image(path, alt="", width=None)` — an explicit image (local path or URL), no
+  discovery.
+- `logo(width=None, alt=None, name="logo")` — theme-aware logo from
+  `docs/logo.{png,svg,...}` (or `logo-dark`/`logo-light` pair).
+- `video(name, width=None, alt=None)` — embeds a video/gif from the screenshots dir.
+- `unsplash(photo, alt=None, width=1200, height=None, credit=None, user=None, photo_id=None, link=None, quality=80, html=False)` —
+  hero image from Unsplash's CDN. `photo` is a photo id like
+  `"photo-1518770660439-4636190af475"` or a full `images.unsplash.com` URL.
+  **Always pass `credit=` and `user=`** — Unsplash's license requires attribution;
+  omitting them renders the image with a `warn()` and no attribution line. `banner:`
+  in config renders one automatically above the title via the same helper.
+
+Image helpers emit plain markdown by default (no `<picture>`/`<img>`), and only
+fall back to HTML when markdown can't express what was asked (a `width=`, an
+explicit `html=True`).
+
+## Structure
+
+- `toc(min_level=2, max_level=3)` — table of contents built from the markdown
+  headings that appear *below* this call in the rendered output.
+- `changelog(n=1)` — the newest `n` entries from `CHANGELOG.md` /
+  `CHANGES.md` / `HISTORY.md` (Keep-a-Changelog `##` headings), with heading levels
+  shifted to nest under the calling context.
+
+## Pulling in files and command output
+
+- `include_file(path)` — raw contents of a file, relative to repo root.
+- `code_block(path, language=None)` — `include_file` wrapped in a fenced code
+  block; language defaults to the file extension.
+- `snippet(path, start, end, language=None, dedent=True)` — the lines between the
+  first line containing `start` and the first line at/after it containing `end`,
+  fenced. Useful for pulling a marked region out of a source file instead of the
+  whole thing.
+- `cli_help(command, language="text", strip_ansi=True)` — runs `command` (shell-split,
+  no shell interpolation) via subprocess and fences stdout/stderr.
+  **Requires `allow_exec: true` in config** — raises `PermissionError` otherwise,
+  since it executes code during render.
+
+## Tables
+
+- `config_table(path, section=None, headers=("Key", "Value"))` — flattens a
+  YAML/TOML/JSON file (optionally a dotted `section=`) into a two-column markdown
+  table.
+- `env_table(path=".env.example")` — parses `KEY=value` lines (using preceding `#`
+  comment lines as descriptions) into a Variable/Default/Description table.
+- `entry_points_table()` — table of `[project.scripts]` from `pyproject.toml`.
+
+## Links
+
+- `gh_link(path="", text=None)` — `{project.owner}/{project.repo}`-relative GitHub
+  URL, e.g. `gh_link("issues", "Issues")`. Needs `project.owner`/`project.repo` set
+  or autodetected from the git remote.
+- `spdx_link(license_id=None)` — link to the SPDX page for the project's license
+  (or an explicit id).
+- `my_ha_link(redirect, text=None, **params)` — a "My Home Assistant" redirect
+  button/link, e.g. `my_ha_link("hacs_repository", owner=..., repository=...)`.
+
+## Layout
+
+- `callout(kind, text)` — a GitHub alert (`kind` is `note`/`tip`/`important`/
+  `warning`/`caution`).
+- `details(summary, body, open=False)` — a `<details>` collapsible.
+- `center(content)` — centers a block of markdown/HTML.
+- `columns(cells, align="center")` — lays out a list of markdown cells
+  side-by-side (as an HTML table row).
+- `contributors(logins=None, size=64)` — avatar grid; `logins` defaults to
+  contributors autodetected from the repo.
+
+## Ecosystem-specific
+
+- `flow_install_cmd()` — Flow Launcher plugin install command.
+- `mc_versions()`, `mod_dependencies()` — Minecraft mod metadata tables (from
+  Gradle `gradle.properties`).
+- `related_repos()` — table from config's `related:` list
+  (`[{repo: other-tool, description: ...}]`).
+- `pyversions_list(sep=", ")` — joined list of supported Python versions.
+
+## Build metadata
+
+- `git_sha(short=True)`, `git_tag()`, `today()` — current commit/tag/date. These
+  change on every render, so a checked-in `README.md` that used them will always
+  show as stale to `readwright check` unless re-rendered immediately before the
+  check (e.g. in a release job). Avoid them in a README that's committed and
+  linted by CI; fine for a render step that runs at publish time.
+
+## Context available in every template
+
+- `project.*` — `name`, `owner`, `repo`, `tagline`, `pypi`, `npm`, `license`,
+  `ci_workflow`, plus anything autodetected from the git remote / `LICENSE` /
+  manifest file. `gh_link()` and badge presets read from here.
+- `vars.*` — free-form values from config's `vars:` map, for anything
+  project-specific that doesn't fit elsewhere.

readwright-0.5.0/AGENTS.md

@@ -0,0 +1,85 @@
+# AGENTS.md
+
+readwright is a Python CLI that renders GitHub `README.md` files from Jinja2 templates
+(`README.md.j2` + `readme.yaml`), with badge, screenshot, TOC, and changelog helpers.
+Package lives under `src/readwright/`; console entry point is `readwright.cli:app`
+(Typer). Python >=3.11, dependency/build managed with `uv` + `hatchling`.
+
+## Setup
+
+```sh
+uv sync --group dev
+```
+
+## Running things
+
+Always run tools through `uv run` (or `uv run tox -e <env>`) so the project's own venv
+and locked dependencies are used, not whatever's on PATH.
+
+```sh
+uv run pytest                    # run the test suite
+uv run pytest tests/test_cli.py  # single file
+uv run ruff check src tests      # lint
+uv run ruff format src tests     # format
+uv run tox                       # full matrix: py311, py312, py313, lint
+uv run tox -e lint               # lint env only (ruff check + ruff format --check)
+uv run readwright render         # regenerate README.md from README.md.j2 + readme.yaml
+uv run readwright check          # fail with a diff if README.md is stale vs. the template
+```
+
+`tests/golden/` holds golden-file fixtures for renderer output — if you touch
+`renderer.py`, `helpers.py`, or any template partial, check whether golden files need
+regenerating rather than hand-editing expected output.
+
+## Before committing
+
+- `pre-commit` is configured (`.pre-commit-config.yaml`): gitleaks, standard hygiene
+  hooks, and `ruff`/`ruff-format` run on every commit; `pytest` and
+  `readwright check` run on `pre-push`. Run `uv run pre-commit run --all-files` if you
+  want to check before pushing without waiting for the hook.
+- **`README.md` is generated — never edit it directly.** Edit `README.md.j2` (the
+  Jinja2 template) and/or `readme.yaml` (the config), then run
+  `uv run readwright render` to regenerate `README.md`. The file itself carries a
+  `<!-- generated by readwright -->` marker; editing it by hand will be silently
+  overwritten and will fail the `readwright check` pre-push hook / CI.
+- Keep `ruff` clean: `select = ["E", "F", "I", "UP", "B", "SIM"]`, line length 100
+  (see `pyproject.toml`).
+- This project versions with hand-bumped `pyproject.toml` (no release-please). Bump
+  `version` yourself for a release-worthy change — patch for fixes, minor for new
+  features/helpers — and follow Conventional Commits (`feat:`, `fix:`, `chore:`, ...).
+
+## Layout
+
+- `src/readwright/cli.py` — Typer commands: `init`, `render`, `check`, `badges`,
+  `blocks`, `show`, `skill`, `completion`.
+- `src/readwright/renderer.py` — Jinja2 environment setup and rendering pipeline.
+- `src/readwright/helpers.py`, `badges.py`, `images.py`, `toc.py`, `changelog.py`,
+  `metadata.py` — the template helper functions exposed to `README.md.j2`
+  (`badge()`, `screenshot()`, `toc()`, `changelog()`, `project.*`, etc.) and repo
+  metadata autodetection (git remote, `LICENSE`, manifest files like
+  `pyproject.toml`/`package.json`/`Cargo.toml`/`go.mod`/`*.csproj`).
+- `src/readwright/config.py` — `readme.yaml` / `[tool.readme]` config model
+  (pydantic).
+- `src/readwright/templates/` — packaged `base.md.j2` and partials that a project's
+  own `README.md.j2` extends/overrides.
+- `examples/` — worked example projects (`kitchen-sink`, `rust-cli`, `go-cli`,
+  `dotnet-tool`, `node-cli`, `config-only`) exercising every helper; useful as
+  reference when adding or changing a helper's behavior.
+- `action.yml` — GitHub Action wrapper for `readwright check`/`render` in CI.
+- `.agents/skills/readwright/` — the agent skill (`SKILL.md` + `helpers.md`) that
+  documents the render/check workflow, config keys and template helpers for coding
+  agents. `.claude/skills/readwright` is a symlink to it, and hatch `force-include`s
+  it into the wheel as `readwright/.agents/skills/readwright/`; `readwright skill
+  --install` copies it out again (in the dev checkout the command falls back to the
+  repo-root directory). When a helper, config
+  key, CLI flag or block is added or changed, update the skill in the same change.
+
+## Testing conventions
+
+- `tests/` mirrors `src/readwright/` module-for-module (`test_badges.py`,
+  `test_renderer.py`, etc.) plus `test_examples.py`, which renders the projects
+  under `examples/` and is a good smoke check when changing template helpers or the
+  renderer.
+- New template helpers should get both a unit test and, where relevant, coverage
+  in `examples/kitchen-sink` since the README documents the full helper set from
+  that project's usage.

readwright-0.5.0/CLAUDE.md

@@ -0,0 +1,18 @@
+# CLAUDE.md
+
+See `AGENTS.md` for project layout, setup, and commands — it applies here too.
+
+## Claude-specific notes
+
+- `README.md` is a generated file (from `README.md.j2` + `readme.yaml`). If a task
+  touches the README, edit the template/config and run `uv run readwright render`;
+  never hand-edit `README.md` itself.
+- After changing anything under `src/readwright/templates/`, `helpers.py`,
+  `badges.py`, `images.py`, `toc.py`, or `changelog.py`, run
+  `uv run pytest tests/test_examples.py` — it renders every project under
+  `examples/` and is the fastest way to catch a broken helper across real usage.
+- Prefer `uv run tox -e lint` over invoking `ruff` directly when you want the same
+  check CI runs (`ruff check` + `ruff format --check`, no auto-fix).
+- This repo is dogfooding itself: `readwright`'s own `README.md.j2`/`readme.yaml`
+  are a real usage example of the tool, not just project docs — check them for
+  helper usage patterns before asking "how do I use X helper".

{readwright-0.3.0 → readwright-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: readwright
-Version: 0.3.0
+Version: 0.5.0
 Summary: Render GitHub READMEs from Jinja2 templates with badge and screenshot helpers
 Project-URL: Homepage, https://github.com/Garulf/readwright
 Project-URL: Issues, https://github.com/Garulf/readwright/issues
@@ -36,6 +36,8 @@ Render GitHub READMEs from Jinja2 templates with badge and screenshot helpers.
 - [Template helpers](#template-helpers)
 - [Configuration](#configuration)
 - [pre-commit and GitHub Actions](#pre-commit-and-github-actions)
+- [Shell completion](#shell-completion)
+- [Agent skill](#agent-skill)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -82,7 +84,7 @@ Run `{{ project.name }} --help`.
 ```
 
 See [`examples/`](https://github.com/Garulf/readwright/tree/main/examples) for a kitchen-sink project using every helper,
-plus Minecraft mod, HACS card and Flow Launcher plugin examples.
+plus Rust, Go, .NET and Node examples showing how the install section adapts per language.
 
 ## Template helpers
 
@@ -167,18 +169,44 @@ stays reproducible in CI. `readwright render --user-config` merges them ad hoc.
 ```yaml
 # .pre-commit-config.yaml
 - repo: https://github.com/Garulf/readwright
-  rev: v0.3.0
+  rev: v0.5.0
   hooks:
     - id: readwright-check
 ```
 
 ```yaml
 # .github/workflows/ci.yml
-- uses: Garulf/readwright@v0.3.0
+- uses: Garulf/readwright@v0.5.0
   with:
     mode: check     # or render
 ```
 
+## Shell completion
+
+`readwright completion <shell>` prints a completion script for bash, zsh, fish or PowerShell.
+It completes subcommands, options and the template names `readwright show` accepts.
+
+```sh
+eval "$(readwright completion bash)"   # add to ~/.bashrc
+eval "$(readwright completion zsh)"    # add to ~/.zshrc, after compinit
+readwright completion fish > ~/.config/fish/completions/readwright.fish
+```
+
+## Agent skill
+
+The repo ships an [agent skill](https://agentskills.io) at `.agents/skills/readwright/`
+that teaches coding agents (Claude Code, Codex, Copilot CLI, Gemini CLI, ...) the
+render/check workflow, the config keys and every template helper, so they edit
+`README.md.j2` instead of the generated `README.md`. Claude Code picks it up from
+this repo automatically via `.claude/skills/readwright`; the same directory is
+bundled inside the wheel, so any project can install it:
+
+```sh
+readwright skill --install                       # copies it to ./.agents/skills/readwright
+readwright skill --install --dest ~/.claude/skills   # or a user-level skills directory
+readwright skill                                 # just print where the bundled copy lives
+```
+
 ## Contributing
 
 Issues and pull requests are welcome at [Garulf/readwright](https://github.com/Garulf/readwright).

{readwright-0.3.0 → readwright-0.5.0}/README.md

@@ -10,6 +10,8 @@ Render GitHub READMEs from Jinja2 templates with badge and screenshot helpers.
 - [Template helpers](#template-helpers)
 - [Configuration](#configuration)
 - [pre-commit and GitHub Actions](#pre-commit-and-github-actions)
+- [Shell completion](#shell-completion)
+- [Agent skill](#agent-skill)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -56,7 +58,7 @@ Run `{{ project.name }} --help`.
 ```
 
 See [`examples/`](https://github.com/Garulf/readwright/tree/main/examples) for a kitchen-sink project using every helper,
-plus Minecraft mod, HACS card and Flow Launcher plugin examples.
+plus Rust, Go, .NET and Node examples showing how the install section adapts per language.
 
 ## Template helpers
 
@@ -141,18 +143,44 @@ stays reproducible in CI. `readwright render --user-config` merges them ad hoc.
 ```yaml
 # .pre-commit-config.yaml
 - repo: https://github.com/Garulf/readwright
-  rev: v0.3.0
+  rev: v0.5.0
   hooks:
     - id: readwright-check
 ```
 
 ```yaml
 # .github/workflows/ci.yml
-- uses: Garulf/readwright@v0.3.0
+- uses: Garulf/readwright@v0.5.0
   with:
     mode: check     # or render
 ```
 
+## Shell completion
+
+`readwright completion <shell>` prints a completion script for bash, zsh, fish or PowerShell.
+It completes subcommands, options and the template names `readwright show` accepts.
+
+```sh
+eval "$(readwright completion bash)"   # add to ~/.bashrc
+eval "$(readwright completion zsh)"    # add to ~/.zshrc, after compinit
+readwright completion fish > ~/.config/fish/completions/readwright.fish
+```
+
+## Agent skill
+
+The repo ships an [agent skill](https://agentskills.io) at `.agents/skills/readwright/`
+that teaches coding agents (Claude Code, Codex, Copilot CLI, Gemini CLI, ...) the
+render/check workflow, the config keys and every template helper, so they edit
+`README.md.j2` instead of the generated `README.md`. Claude Code picks it up from
+this repo automatically via `.claude/skills/readwright`; the same directory is
+bundled inside the wheel, so any project can install it:
+
+```sh
+readwright skill --install                       # copies it to ./.agents/skills/readwright
+readwright skill --install --dest ~/.claude/skills   # or a user-level skills directory
+readwright skill                                 # just print where the bundled copy lives
+```
+
 ## Contributing
 
 Issues and pull requests are welcome at [Garulf/readwright](https://github.com/Garulf/readwright).

{readwright-0.3.0 → readwright-0.5.0}/README.md.j2

@@ -37,7 +37,7 @@ Run `{{ project.name }} --help`.
 ```
 
 See [`examples/`]({{ gh_link("tree/main/examples") }}) for a kitchen-sink project using every helper,
-plus Minecraft mod, HACS card and Flow Launcher plugin examples.
+plus Rust, Go, .NET and Node examples showing how the install section adapts per language.
 
 ## Template helpers
 
@@ -134,4 +134,30 @@ stays reproducible in CI. `readwright render --user-config` merges them ad hoc.
     mode: check     # or render
 ```
 
+## Shell completion
+
+`readwright completion <shell>` prints a completion script for bash, zsh, fish or PowerShell.
+It completes subcommands, options and the template names `readwright show` accepts.
+
+```sh
+eval "$(readwright completion bash)"   # add to ~/.bashrc
+eval "$(readwright completion zsh)"    # add to ~/.zshrc, after compinit
+readwright completion fish > ~/.config/fish/completions/readwright.fish
+```
+
+## Agent skill
+
+The repo ships an [agent skill](https://agentskills.io) at `.agents/skills/readwright/`
+that teaches coding agents (Claude Code, Codex, Copilot CLI, Gemini CLI, ...) the
+render/check workflow, the config keys and every template helper, so they edit
+`README.md.j2` instead of the generated `README.md`. Claude Code picks it up from
+this repo automatically via `.claude/skills/readwright`; the same directory is
+bundled inside the wheel, so any project can install it:
+
+```sh
+readwright skill --install                       # copies it to ./.agents/skills/readwright
+readwright skill --install --dest ~/.claude/skills   # or a user-level skills directory
+readwright skill                                 # just print where the bundled copy lives
+```
+
 {% endblock %}

{readwright-0.3.0 → readwright-0.5.0}/examples/README.md

@@ -1,15 +1,17 @@
 # readwright examples
 
-Each directory is a self-contained fake project with a `readme.yaml`, a `README.md.j2` and the
-`README.md` that `readwright render` produces from them. Run `readwright render` inside one to regenerate.
+Each directory is a self-contained fake project with a `readme.yaml` (some also have a `README.md.j2`)
+and the `README.md` that `readwright render` produces from them. Run `readwright render` inside one to
+regenerate.
 
 | Example | Shows |
 | --- | --- |
 | [kitchen-sink](kitchen-sink/) | Every general helper: logo/center header, badge presets + custom + donation badges with a global style, toc, screenshots with captions and dark/light variants, subdir gallery, `include_file`, `cli_help`, `snippet`, `details`, `callout`, `config_table`, `env_table`, `entry_points_table`, `columns`, `video`, `changelog`, `gh_link`, `related_repos`, `contributors`, `git_sha`/`git_tag`/`today`, `spdx_link`, an `unsplash()` hero image, a repo-local partial override |
 | [config-only](config-only/) | No template at all: a fully annotated `readme.yaml` using every config key (including an Unsplash `banner:`), rendered by the packaged `base.md.j2`. Read it as the config reference |
-| [minecraft-mod](minecraft-mod/) | Gradle/NeoForge detection, Unsplash `banner:`, `modrinth`/`curseforge` badges, `mc_versions()`, `mod_dependencies()` |
-| [ha-card](ha-card/) | `hacs.json` detection, `unsplash()` from an image URL, `hacs`/`ha-version` badges, `my_ha_link()`, `code_block()` |
-| [flow-plugin](flow-plugin/) | Flow Launcher `plugin.json` detection and the `pm install` snippet |
+| [rust-cli](rust-cli/) | `Cargo.toml` detection and the `cargo install` snippet; a custom `{shield: ...}` badge for crates.io, since there's no built-in preset |
+| [go-cli](go-cli/) | `go.mod` detection and the `go install ...@latest` snippet |
+| [dotnet-tool](dotnet-tool/) | `*.csproj` detection (`PackAsTool`) and the `dotnet tool install --global` snippet |
+| [node-cli](node-cli/) | `package.json` detection, the `npm install` snippet and the `npm` badge preset |
 
 The kitchen sink uses `git_sha()` and `today()`, so its committed `README.md` will always be a little
 behind; that is deliberate, to show why those helpers are a poor fit for `readwright check`.

readwright-0.5.0/examples/dotnet-tool/DotTool.csproj

@@ -0,0 +1,10 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <PackAsTool>true</PackAsTool>
+    <PackageId>DotTool.Cli</PackageId>
+    <Version>2.1.0</Version>
+    <Description>A .NET global tool for scaffolding project templates</Description>
+    <PackageLicenseExpression>MIT</PackageLicenseExpression>
+  </PropertyGroup>
+</Project>

readwright-0.5.0/examples/dotnet-tool/README.md

@@ -0,0 +1,20 @@
+<!-- generated by readwright from base.md.j2; edit the template, not this file -->
+# DotTool.Cli
+
+A .NET global tool for scaffolding project templates
+
+[![License](https://img.shields.io/github/license/octocat/dottool)](https://github.com/octocat/dottool/blob/main/LICENSE) [![CI](https://img.shields.io/github/actions/workflow/status/octocat/dottool/ci.yml)](https://github.com/octocat/dottool/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/octocat/dottool)](https://github.com/octocat/dottool/releases/latest) [![version](https://img.shields.io/badge/version-2.1.0-informational)](https://github.com/octocat/dottool) [![nuget](https://img.shields.io/badge/nuget-v2.1.0-004880?logo=nuget)](https://www.nuget.org/packages/DotTool.Cli)
+
+## Installation
+
+```sh
+dotnet tool install --global DotTool.Cli
+```
+
+## Contributing
+
+Issues and pull requests are welcome at [octocat/dottool](https://github.com/octocat/dottool).
+
+## License
+
+MIT

readwright-0.5.0/examples/dotnet-tool/readme.yaml

@@ -0,0 +1,7 @@
+badges:
+  - license
+  - {preset: ci, workflow: ci.yml}
+  - github-release
+  - version
+  - {shield: {label: nuget, message: v2.1.0, color: 004880, logo: nuget, link: https://www.nuget.org/packages/DotTool.Cli}}
+project: {owner: octocat, repo: dottool}