mdcompose 0.1.3__tar.gz → 0.2.0__tar.gz

mdcompose-0.2.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+ko_fi: rovetown

{mdcompose-0.1.3 → mdcompose-0.2.0}/.github/workflows/ci.yml

@@ -292,27 +292,28 @@ jobs:
             esac
           done
 
-  # DORMANT, repo-gated. The suite (tests/benchmarks) and the `benchmark`
-  # dependency group both exist; what is missing is a CodSpeed project, which
-  # needs the GitHub repo. CodSpeed runs the benchmarks instrumented rather than
-  # wall-clock, so the numbers are stable across runners, and it posts the delta
-  # as a pull request check rather than failing hard. Free for open source. To
-  # enable: connect the repo at codspeed.io, uncomment this job, and leave it
-  # out of the all-green needs list (benchmarks never block a merge).
-  #
-  # benchmarks:
-  #   name: benchmarks
-  #   runs-on: ubuntu-latest
-  #   timeout-minutes: 20
-  #   steps:
-  #     - uses: actions/checkout@v4
-  #       with:
-  #         persist-credentials: false
-  #     - uses: astral-sh/setup-uv@v5
-  #       with:
-  #         enable-cache: true
-  #         cache-dependency-glob: uv.lock
-  #     - run: uv sync --locked --group benchmark
-  #     - uses: CodSpeedHQ/action@v3
-  #       with:
-  #         run: uv run --no-sync pytest tests/benchmarks --codspeed
+  # CodSpeed runs the benchmarks instrumented rather than wall-clock, so the
+  # numbers are stable across runners, and it posts the delta as a pull request
+  # check rather than failing hard. Free for open source. Not in the all-green
+  # needs list: benchmarks never block a merge. Needs the repo connected at
+  # codspeed.io once before its first run.
+  benchmarks:
+    name: benchmarks
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      id-token: write # OpenID Connect authentication with CodSpeed
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv sync --locked --group benchmark
+      - uses: CodSpeedHQ/action@373d6868929f444bc08d901fd0eb0ad52a8875ea # v5.2.1
+        with:
+          run: uv run --no-sync pytest tests/benchmarks --codspeed
+          mode: "simulation"

{mdcompose-0.1.3 → mdcompose-0.2.0}/.github/workflows/supply-chain.yml

@@ -85,7 +85,7 @@ jobs:
         with:
           persist-credentials: false
 
-      - uses: google/osv-scanner-action/osv-scanner-action@6e4298ebc4db23e847df9b2e2de2939d6f066c67 # v2.5.1
+      - uses: google/osv-scanner-action/osv-scanner-action@a345acffa64b0eaede81a3d9aae6141214d9c8fc # v2.6.0
         with:
           scan-args: >-
             --lockfile=uv.lock

{mdcompose-0.1.3 → mdcompose-0.2.0}/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to mdcompose are recorded here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.2.0 (2026-09-14)
+
+### Added
+
+- compose agent skills alongside AGENTS.md and CLAUDE.md
+
 ## v0.1.3 (2026-09-11)
 
 ## v0.1.2 (2026-09-11)

{mdcompose-0.1.3 → mdcompose-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mdcompose
-Version: 0.1.3
+Version: 0.2.0
 Summary: Keep CLAUDE.md and AGENTS.md in sync and composed from a personal snippet library, without hand-editing every project
 Project-URL: Homepage, https://github.com/Rovetown/mdcompose
 Project-URL: Repository, https://github.com/Rovetown/mdcompose
@@ -40,15 +40,14 @@ Description-Content-Type: text/markdown
 
 <div align="center">
 
-[![PyPI](https://img.shields.io/pypi/v/mdcompose?style=for-the-badge)](https://pypi.org/project/mdcompose/) [![Python](https://img.shields.io/pypi/pyversions/mdcompose?style=for-the-badge)](https://pypi.org/project/mdcompose/) [![CI](https://img.shields.io/github/actions/workflow/status/Rovetown/mdcompose/ci.yml?branch=main&style=for-the-badge&label=CI)](https://github.com/Rovetown/mdcompose/actions/workflows/ci.yml) [![OpenSSF Scorecard](https://img.shields.io/ossf-scorecard/github.com/Rovetown/mdcompose?style=for-the-badge&label=scorecard)](https://scorecard.dev/viewer/?uri=github.com/Rovetown/mdcompose) [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](https://github.com/Rovetown/mdcompose/blob/main/LICENSE) [![Downloads](https://img.shields.io/pypi/dm/mdcompose?style=for-the-badge)](https://pypi.org/project/mdcompose/)
+[![PyPI](https://img.shields.io/pypi/v/mdcompose?style=for-the-badge)](https://pypi.org/project/mdcompose/) [![Python](https://img.shields.io/pypi/pyversions/mdcompose?style=for-the-badge)](https://pypi.org/project/mdcompose/) [![CI](https://img.shields.io/github/actions/workflow/status/Rovetown/mdcompose/ci.yml?branch=main&style=for-the-badge&label=CI)](https://github.com/Rovetown/mdcompose/actions/workflows/ci.yml) [![CodSpeed Badge](https://img.shields.io/endpoint?url=https://app.codspeed.io//badge.json&style=for-the-badge)](https://app.codspeed.io//Rovetown/mdcompose?utm_source=badge) [![OpenSSF Scorecard](https://img.shields.io/ossf-scorecard/github.com/Rovetown/mdcompose?style=for-the-badge&label=scorecard)](https://scorecard.dev/viewer/?uri=github.com/Rovetown/mdcompose) [![OpenSSF Best Practices](https://img.shields.io/cii/summary/14614?style=for-the-badge&label=best%20practices)](https://www.bestpractices.dev/projects/14614) [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](https://github.com/Rovetown/mdcompose/blob/main/LICENSE) [![Downloads](https://img.shields.io/pypi/dm/mdcompose?style=for-the-badge)](https://pypi.org/project/mdcompose/) [![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/Y8Y31VUCGT)
 
 </div>
 
 Most repositories need the same handful of instructions for AI coding agents: how commits are written, which test command to run, which files not to touch.
 mdcompose keeps those as small snippets in one place and builds each project's `AGENTS.md` and `CLAUDE.md` from the ones you pick, so you stop copying the same paragraphs between repositories.
 
-> `mdcompose` composes Markdown.
-> It is unrelated to Docker Compose; the shared `-compose` suffix is a coincidence.
+> `mdcompose` composes Markdown. It is unrelated to Docker Compose.
 
 ## Highlights
 
@@ -89,11 +88,9 @@ uvx mdcompose doctor
 
 The whole flow, start to finish:
 
-<!-- demo GIF: docs/assets/mdcompose-demo.gif -- not yet recorded, see TODO.md. Restore the <img> below once it exists. -->
-
 <div align="center">
 
-*(a short demo recording of `init` and `doctor` goes here -- not yet recorded)*
+<img src="https://raw.githubusercontent.com/Rovetown/mdcompose/main/docs/assets/mdcompose-demo.gif" alt="mdcompose demo: init's interactive picker composing AGENTS.md and CLAUDE.md from selected snippets, then doctor confirming both are clean" width="700">
 
 </div>
 

{mdcompose-0.1.3 → mdcompose-0.2.0}/README.md

@@ -10,15 +10,14 @@
 
 <div align="center">
 
-[![PyPI](https://img.shields.io/pypi/v/mdcompose?style=for-the-badge)](https://pypi.org/project/mdcompose/) [![Python](https://img.shields.io/pypi/pyversions/mdcompose?style=for-the-badge)](https://pypi.org/project/mdcompose/) [![CI](https://img.shields.io/github/actions/workflow/status/Rovetown/mdcompose/ci.yml?branch=main&style=for-the-badge&label=CI)](https://github.com/Rovetown/mdcompose/actions/workflows/ci.yml) [![OpenSSF Scorecard](https://img.shields.io/ossf-scorecard/github.com/Rovetown/mdcompose?style=for-the-badge&label=scorecard)](https://scorecard.dev/viewer/?uri=github.com/Rovetown/mdcompose) [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](https://github.com/Rovetown/mdcompose/blob/main/LICENSE) [![Downloads](https://img.shields.io/pypi/dm/mdcompose?style=for-the-badge)](https://pypi.org/project/mdcompose/)
+[![PyPI](https://img.shields.io/pypi/v/mdcompose?style=for-the-badge)](https://pypi.org/project/mdcompose/) [![Python](https://img.shields.io/pypi/pyversions/mdcompose?style=for-the-badge)](https://pypi.org/project/mdcompose/) [![CI](https://img.shields.io/github/actions/workflow/status/Rovetown/mdcompose/ci.yml?branch=main&style=for-the-badge&label=CI)](https://github.com/Rovetown/mdcompose/actions/workflows/ci.yml) [![CodSpeed Badge](https://img.shields.io/endpoint?url=https://app.codspeed.io//badge.json&style=for-the-badge)](https://app.codspeed.io//Rovetown/mdcompose?utm_source=badge) [![OpenSSF Scorecard](https://img.shields.io/ossf-scorecard/github.com/Rovetown/mdcompose?style=for-the-badge&label=scorecard)](https://scorecard.dev/viewer/?uri=github.com/Rovetown/mdcompose) [![OpenSSF Best Practices](https://img.shields.io/cii/summary/14614?style=for-the-badge&label=best%20practices)](https://www.bestpractices.dev/projects/14614) [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](https://github.com/Rovetown/mdcompose/blob/main/LICENSE) [![Downloads](https://img.shields.io/pypi/dm/mdcompose?style=for-the-badge)](https://pypi.org/project/mdcompose/) [![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/Y8Y31VUCGT)
 
 </div>
 
 Most repositories need the same handful of instructions for AI coding agents: how commits are written, which test command to run, which files not to touch.
 mdcompose keeps those as small snippets in one place and builds each project's `AGENTS.md` and `CLAUDE.md` from the ones you pick, so you stop copying the same paragraphs between repositories.
 
-> `mdcompose` composes Markdown.
-> It is unrelated to Docker Compose; the shared `-compose` suffix is a coincidence.
+> `mdcompose` composes Markdown. It is unrelated to Docker Compose.
 
 ## Highlights
 
@@ -59,11 +58,9 @@ uvx mdcompose doctor
 
 The whole flow, start to finish:
 
-<!-- demo GIF: docs/assets/mdcompose-demo.gif -- not yet recorded, see TODO.md. Restore the <img> below once it exists. -->
-
 <div align="center">
 
-*(a short demo recording of `init` and `doctor` goes here -- not yet recorded)*
+<img src="https://raw.githubusercontent.com/Rovetown/mdcompose/main/docs/assets/mdcompose-demo.gif" alt="mdcompose demo: init's interactive picker composing AGENTS.md and CLAUDE.md from selected snippets, then doctor confirming both are clean" width="700">
 
 </div>
 

{mdcompose-0.1.3 → mdcompose-0.2.0}/TODO.md

@@ -5,129 +5,42 @@ management CLI. Everything here is either open or a decision worth keeping.
 
 ## Next
 
-The codebase and the automation are done. The repo is live at
-`github.com/Rovetown/mdcompose` and the account-side setup in "Repository and
-release setup" below is complete (ruleset, `RELEASE_TOKEN`, the `pypi` and
-`testpypi` environments, both trusted publishers, Dependabot, private
-vulnerability reporting). What remains is the first release, a few follow-ups,
-and a set of OpenSSF Scorecard items folded into the sequence at the step each
-one belongs to. The Scorecard reasoning is in [`docs/scorecard.md`](docs/scorecard.md).
-
-### Scorecard, current state
-
-1. Done. [`SECURITY.md`](SECURITY.md) carries the private-advisory URL
-   (`https://github.com/Rovetown/mdcompose/security/advisories/new`). Confirmed
-   in the `scorecard.yml` run for commit `b730e9e`: Security-Policy, along with
-   Signed-Releases and Packaging, all score 10. Overall: 7.2. Remaining gap is
-   Maintained (0, clears at 90 days), CII-Best-Practices (0, needs
-   registration, see step 7 below), and the accepted solo-maintainer limits
-   (Code-Review, Contributors, Branch-Protection, Fuzzing). See
-   [`docs/scorecard.md`](docs/scorecard.md) for the full detail.
-
-### First release
-
-2. Done, verifies at step 4. `release.yml` `build` job runs
-   `actions/attest-build-provenance` over `dist/*` (job now has
-   `id-token: write` and `attestations: write`), stages the bundle as
-   `mdcompose.intoto.jsonl`, and the `github-release` job attaches it to the
-   Release (assets are now listed explicitly, since the artifact download keeps
-   the `dist/` subdirectory and `gh release create` rejects a directory arg).
-   A SLSA `*.intoto.jsonl` scores 10 on Signed-Releases. Only runs on a stable
-   tag; pre-releases get no GitHub Release. Nothing to verify until the first
-   stable release lands the assets.
-3. Done. Alpha dry run published `0.1.0a0` to TestPyPI, verified end to end:
-   `release.yml` build -> attest -> TestPyPI, `pypi` and `github-release` jobs
-   correctly skipped, `gh attestation verify` passed online and against the
-   staged `mdcompose.intoto.jsonl`, clean-venv `pip install` works. Two bugs
-   found and fixed on the way: `cz bump` left `uv.lock` stale (fixed in #12,
-   `bump.yml` now relocks and amends before the tag push) and a deleted
-   prerelease tag left commitizen unable to bound the next changelog (fixed by
-   reverting the botched bump in #13).
-
-### README (active, before the stable release)
-
-The README should be good before `0.1.0` reaches PyPI, since `readme =
-"README.md"` becomes the PyPI long description. Structure is agreed: lean
-front-door, ~130 to 200 lines, `for-the-badge` style shields badges, near-zero
-emoji, ASCII diagrams and trees (no mermaid, because PyPI does not render it),
-HTML only for layout. Prose is neutral-dev, accessible to a non-expert without
-dropping the technical terms.
-
-Done: [`README.md`](README.md) written (from the v3 draft, demo GIF placed in Quickstart
-rather than Highlights, since the GIF shows the flow the Quickstart walks
-through), both drafts deleted, `scripts/check_ascii.py` exempts [`README.md`](README.md)
-via a `SKIP_FILES` set (Decisions log below records it), reference-level detail
-moved out to [`docs/concepts.md`](docs/concepts.md), and a logo added: `docs/assets/mdcompose-logo.svg`
-in the centered header (replacing the `# mdcompose` text heading), referenced
-by the same absolute `raw.githubusercontent.com/.../main/...` URL as the demo
-GIF so it also renders on PyPI, and `docs/assets/**` excluded from the sdist in
-`pyproject.toml` (`[tool.hatch.build]`, verified with a real `uv build`; the
-wheel was never affected, it already only packages `mdcompose`). Badges use
-`style=for-the-badge`, not `flat-square`. Not yet committed.
-
-Still to finish:
-
-- **Record the demo GIF.** Deliberately deferred, not blocking `0.1.0`: no
-  time to set up the recording right now. The README's Quickstart spot now
-  holds an italic text placeholder instead of a broken `<img>` tag, with a
-  comment naming exactly what to restore once the GIF exists. Plan for when
-  time allows: script an asciinema recording of the real flow (create a
-  snippet file, `mdcompose init` with the picker, `mdcompose doctor` showing a
-  clean then drifted state), convert with
-  `agg demo.cast docs/assets/mdcompose-demo.gif`. Keep it short, roughly 15 to
-  25 seconds, one clear take. Shot list to write first: exact commands, where
-  to pause, terminal size and theme so it is re-recordable when output
-  changes. `docs/assets/` already exists (holds the logo).
-- **Verify the badges resolve** once `0.1.0` is on PyPI (the PyPI, pyversions,
-  and scorecard badges 404 or show "unknown" until then).
-
-### After the README, resume the release
-
-4. Done. `bump.yml` ran with channel `stable`, `0.1.0a0` -> `0.1.0`, `v0.1.0`
-   tagged, the `pypi` environment approved. `v0.1.0` is live on PyPI and the
-   first GitHub Release exists with the SBOM and attestation assets attached.
-5. Done. [`CHANGELOG.md`](CHANGELOG.md)'s `## v0.1.0` entry replaced cz's thin
-   auto body ("break the cli and command import cycle", "relock uv.lock",
-   etc., none of which belong in a *user-facing* changelog) with "Initial
-   public release." plus the full `### Added` command list restored verbatim
-   from the old `[Unreleased]` section (recovered from commit `2252051`, since
-   the alpha bump had already consumed it) and the `### Security`
-   SLSA-provenance note. cz's `### Changed` and `### Fixed` sections dropped:
-   there is no prior release to change from.
-
-Also done in this pass, discovered from the live PyPI listing: the
-`pypi/pyversions` badge showed a bare "Python 3" rather than the real
-supported range, because shields.io reads PyPI's classifiers, not
-`requires-python`, and only a bare `Programming Language :: Python :: 3` was
-listed. `pyproject.toml` now lists `3.11` through `3.14` individually,
-matching the CI matrix. This only takes effect on the *next* release; it does
-not retroactively fix the metadata already published for `0.1.0`.
-
-### After the first release
-
-6. **Post-release hardening.** Partly done: `Development Status` moved to
-   `4 - Beta` (the v1 feature set is complete and tested -- all 8 OpenSpec
-   changes shipped, 93%+ coverage, mutation-tested, hardening review done --
-   but pre-1.0 semver still allows a breaking change, so Beta fits better than
-   a Stable claim; also takes effect on the next release only). Still open:
-   point `platform.ONEDRIVE_HELP_URL` at a real page.
-7. **OpenSSF Best Practices passing badge.** Register the repo at
-   bestpractices.dev, complete the passing questionnaire (most criteria are
-   already met by the existing CI, tests, license, and static analysis), embed
-   the badge in the README. Scorecard's CII-Best-Practices check reads it
-   through the API: 0 to 5. Silver and gold are not attainable for a
-   solo-maintained project, so passing is the target. See [`docs/scorecard.md`](docs/scorecard.md).
-8. **Dismiss the permanent Scorecard code-scanning alerts.** Code-Review,
-   Branch-Protection, and Fuzzing are solo-maintainer structural or a
-   deliberate non-goal (see [`docs/scorecard.md`](docs/scorecard.md), Accepted limitations). Dismiss
-   them as "won't fix" in the Security tab so the alert count stays meaningful;
-   leave Maintained and CII-Best-Practices to self-resolve.
-
-### Not planned
-
-9. **Fuzzing.** Left at 0. Scorecard does not detect Python Hypothesis, and an
-   Atheris plus ClusterFuzzLite setup is out of proportion to the risk for two
-   small parsers. Revisit only if the parser surface grows.
+The codebase, the automation, and the account-side release setup are all done.
+The repo is live at `github.com/Rovetown/mdcompose`, `v0.1.3` is on PyPI, and
+the WSL demo recording did a clean-venv `pip install` against that real
+published package. What is left is a short list of items that are either
+genuinely still open or deliberately deferred to a future trigger (a date, a
+second maintainer, a badge cache catching up). The Scorecard reasoning behind
+the deferred items is in [`docs/scorecard.md`](docs/scorecard.md).
+
+Done: CodSpeed badge added to the README badge row, `style=for-the-badge`,
+placed next to the CI badge. Done: PyPI, Python-versions, and OpenSSF
+Scorecard badges confirmed rendering real values, not "unknown" or a
+broken-image placeholder.
+
+### Deferred
+
+- **OpenSSF Scorecard: Maintained check.** Scores 0 regardless of activity
+  until the repository passes 90 days old; it was created 2026-09-09, so this
+  clears around 2026-12-08. Nothing to do before then; revisit only to
+  confirm the score actually moved once that date passes.
+- **OpenSSF Scorecard: code-scanning alerts left open, not dismissed.**
+  Code-Review, Branch-Protection, and Fuzzing are solo-maintainer structural
+  limits (see [`docs/scorecard.md`](docs/scorecard.md), Accepted
+  limitations), but "won't fix" is not a permanent label here -- the
+  constraint holds only while there is one maintainer. Revisit once a second
+  maintainer or a collaborator with review rights joins: Code-Review and
+  Branch-Protection stop being structural at that point, and Fuzzing can be
+  reconsidered on its own merits.
+- **Fuzzing.** Left at 0 on purpose, not a gap to close now. Scorecard does
+  not detect Python Hypothesis (already used in the parser tests), and an
+  Atheris plus ClusterFuzzLite setup is out of proportion to the risk for two
+  small parsers. Revisit only if the parser surface grows materially.
+- **Add each new Python to the CI matrix by hand** when its final release
+  ships (annual cadence, not worth automating). 3.15 is deferred until then
+  (was rc2 on 2026-09-13, final due October 2026): a prerelease-specific
+  version string in `uv sync --python` is not worth carrying for a few weeks
+  of coverage the final release gets for free.
 
 ## Where things live
 
@@ -200,6 +113,33 @@ not retroactively fix the metadata already published for `0.1.0`.
   `version_provider = "scm"` handshake with commitizen) than a solo project
   bumping one line per release needs. Decision closed.
 
+- **Demo GIF recording needs a pty CPR trick, if it is ever re-recorded.**
+  `questionary`'s picker sits on `prompt_toolkit`, which probes the terminal
+  with a cursor-position request (`\x1b[6n`) before it will live-redraw. A
+  bare `pexpect.spawn` pty never answers that probe, so the picker silently
+  degrades to a static, non-redrawing render -- every keystroke lands, but
+  nothing visibly updates until the final "done (N selections)" line. Fix
+  used for `docs/assets/mdcompose-demo.gif`: a background thread reads the
+  child pty directly (`os.read` on `child.child_fd`, not `child.expect`,
+  since only one reader can drain the fd), mirrors every byte to stdout for
+  `asciinema` to capture, and answers any `\x1b[6n` it sees with a plausible
+  `\x1b[<row>;1R` immediately. That alone is what makes the recording a real
+  live checkbox animation instead of a slideshow. The driver script and seed
+  snippets were scratch-only (`temp/`), never committed, so this needs
+  redoing from scratch next time.
+- **PyPI's `pyversions` badge reads classifiers, not `requires-python`.**
+  `pyproject.toml` had only a bare `Programming Language :: Python :: 3`
+  classifier, so shields.io rendered the badge as "Python 3" instead of the
+  real supported range. Fixed by listing `3.11` through `3.14` individually
+  as classifiers, matching the CI matrix. Takes effect only on the next
+  release; already-published metadata for a prior version is not
+  retroactively fixed.
+- **OpenSSF Best Practices registration is project 14614.**
+  `https://www.bestpractices.dev/projects/14614`, homepage set to the GitHub
+  repo URL, Passing tier across all six categories. Needed again only if the
+  self-assessment has to be revisited (a criterion changes, or silver/gold
+  becomes reachable with a second maintainer).
+
 ## Reference docs
 
 - [`docs/versioning-explained.md`](docs/versioning-explained.md) - how a number becomes `0.3.2` vs `0.4.0` vs
@@ -233,9 +173,10 @@ free for public or personal-account use:
 - OpenSSF Scorecard - free
 - CodeQL - free for public repos
 
-Excluded because metered or paid: Codecov, CodSpeed (CodSpeed has a free OSS
-tier and is kept dormant, see below). Coverage is gated in-repo with
-`coverage --fail-under` and uploaded as an artifact, never sent to a service.
+Excluded because metered or paid: Codecov. CodSpeed is wired (free OSS tier,
+connected at codspeed.io, see the `benchmarks` job below); Coverage itself is
+gated in-repo with `coverage --fail-under` and uploaded as an artifact, never
+sent to a service.
 
 One thing to confirm before wiring: `gitleaks/gitleaks-action` needs a free
 `GITLEAKS_LICENSE` key **only when the repo owner is a GitHub organisation**. If
@@ -257,7 +198,8 @@ One thing to confirm before wiring: `gitleaks/gitleaks-action` needs a free
 
 In the repo now: `ci.yml` (test matrix 3 OS x Python 3.11-3.14, `lint` (ruff +
 `mypy` + `deptry`), `coverage`, `ascii`, `build`, plus `hooks`, `commits`,
-`gitleaks`, `all-green`), `supply-chain.yml` (`licenses`, `audit`, `osv`,
+`gitleaks`, `benchmarks` (CodSpeed, not in `all-green`'s needs), `all-green`),
+`supply-chain.yml` (`licenses`, `audit`, `osv`,
 `sbom`), `dependency-review.yml` (PR-only, `deny-licenses` = the copyleft
 families), `release.yml` (`v*` tag), `bump.yml` (the dispatched release button),
 `mutation.yml` (weekly `mutmut`), `codeql.yml`, `scorecard.yml`,
@@ -303,11 +245,15 @@ tag through.
 
 ### Dormant - shipped commented, with an `# ENABLE WHEN:` marker
 
-- `codspeed` job in `ci.yml` - ENABLE WHEN the repo exists and a CodSpeed
-  project is connected. The benchmark suite is written; only the hosted runner
-  is missing.
 - all-contributors config - ENABLE WHEN the first outside contributor lands.
 
+The `benchmarks` job in `ci.yml` was in this list; it is now uncommented,
+pinned, and connected at codspeed.io (run `34781861376`, commit `4b43aa5`,
+2026-09-13, uploaded successfully after an earlier run failed with a
+`401 Unauthorized` before the account-side connection existed). It runs on
+every push and PR but is not in `all-green`'s needs list, so it cannot block a
+merge.
+
 (`mutation.yml` is not dormant - it ships active on a weekly cron, non-blocking.)
 
 ### Local iteration
@@ -349,19 +295,13 @@ alerts + security updates and private vulnerability reporting. Allow the
 
 ### Explicitly not in the pipeline
 
-Codecov / CodSpeed / any metered service (cost); git-cliff / towncrier
+Codecov / any other metered service (cost); git-cliff / towncrier
 (commitizen writes the changelog); release-please / python-semantic-release
 (rejected, philosophy C is the model); a triage bot (issue volume); hatch-vcs /
 `hatch version` / setuptools-scm (no version-derivation layer; `cz bump` writes
 `version` directly); trufflehog as a hook or job (it is a one-time local
 pre-publish run only).
 
-## Open work
-
-Things that are not behavior, so they carry no core-contract change.
-
-- [ ] Add an optional funding link via `.github/FUNDING.yml` and a line in the README footer. Deferred at the maintainer's request.
-
 ## Standing decision: competitive landscape
 
 Three tools cover the core idea of a personal library of reusable snippets
@@ -394,58 +334,19 @@ but because it is the active brand of an existing company (ContextSmith Inc.,
 B2B customer-intelligence SaaS, founded 2015, Sunnyvale). Fine for purely
 personal unpublished use, never for anything released.
 
-## Repository and release setup (needs the repo)
-
-Plan and rationale: [`docs/publishing.md`](docs/publishing.md). In-repo artifacts (`release.yml`,
-[`CHANGELOG.md`](CHANGELOG.md), `renovate.json`, `codeql.yml`, `scorecard.yml`,
-`python-eol.yml`, workflow `permissions`) are all in place; the CI/CD pipeline
-section is the reference. What is left is account-side, roughly in order.
-
-Status, 2026-09-10: every account-side item in this list is done. The repo is
-public, the ruleset is active, `RELEASE_TOKEN` and both Actions environments
-exist, both trusted publishers are registered, and `pre-commit.ci` is enabled.
-The checkboxes below are kept for the record and are not re-ticked here. The
-live remaining work is in the `Next` section at the top of this file.
-
-- [ ] Immediately before making the repo public: run `trufflehog git file://.
-  --only-verified` over the full local history, confirm clean. One time, local,
-  never a hook or a job.
-- [ ] Create `github.com/Rovetown/mdcompose` and push. Enable private
-  vulnerability reporting (the CODE_OF_CONDUCT contact points at it), Dependabot
-  alerts, and Dependabot security updates.
-- [ ] Confirm whether `Rovetown` is a personal account or an organisation: an
-  organisation needs a free `GITLEAKS_LICENSE` key for `gitleaks-action`, a
-  personal account does not.
-- [ ] Branch protection on `main`: require `all-green`, `supply chain / *`, and
-  `CodeQL`; require one review; require the branch up to date; require linear
-  history; block force-push. Allow the `bump.yml` token identity to bypass the
-  push restriction.
-- [ ] Create a fine-grained PAT (or GitHub App token) with `contents: write`,
-  store as the `RELEASE_TOKEN` secret; `bump.yml` uses it so the tag push
-  triggers `release.yml` and the bump commit clears branch protection.
-- [ ] Register a PyPI pending publisher for `mdcompose` (owner `Rovetown`,
-  repo `mdcompose`, workflow `release.yml`, environment `pypi`), and the same
-  on TestPyPI.
-- [ ] Add GitHub Actions environments `pypi` (required reviewer) and `testpypi`.
-- [ ] Enable `pre-commit.ci` on the repo and delete the `hooks` job from
-  `ci.yml` (run one, not both).
-
-Post-repo, at the release that earns it:
-
-- [x] Move the `Development Status` classifier off `3 - Alpha`. Done: moved to
-  `4 - Beta` (see the `Next` section above for the reasoning).
-- [ ] Add a new Python to the CI matrix by hand when its first release
-  candidate lands (annual, not worth a regex manager).
-- [ ] Point `platform.ONEDRIVE_HELP_URL` (`https://mdcompose.dev/onedrive`) at a
-  real how-to-exclude video before the first release.
-- [ ] Wire the CodSpeed `benchmarks` job once the repo is up (it is written,
-  just commented).
-- [ ] Optional: write up the OneDrive warning in [`docs/core-contract.md`](docs/core-contract.md) if the
-  project keeps that discipline post-v1. Implemented directly for now.
-
-## Roadmap (later)
-
-Everything here is a later, larger effort. The codebase-wide quality pass is
+## Repository and release setup
+
+Done, 2026-09-10. Plan and rationale: [`docs/publishing.md`](docs/publishing.md).
+Repo public, ruleset active, `RELEASE_TOKEN` and both Actions environments
+exist, both trusted publishers registered, `pre-commit.ci` enabled. Nothing
+open here; live remaining work is in `Next` at the top of this file.
+
+## Roadmap (later, deferred)
+
+This section is TODO the same as `Next`, just longer-horizon: each item below
+is real backlog, not idle brainstorming, and stays here until it is either
+scoped into an OpenSpec change or explicitly dropped. The codebase-wide
+quality pass is
 done: strict typing enforced in CI, a ratcheting coverage floor with its own
 job, a benchmark suite with a recorded baseline, the file-I/O hardening review
 and parser fuzzing. `platform.py` and the interactive questionary pickers in
@@ -475,6 +376,10 @@ having a real backing plan for, not yet an OpenSpec change.
   reuses the existing core rather than forking it, the standing bar for
   everything in this Roadmap section.
 
+### Third-party integrations
+
+- [ ] Research and, where practical, build integrations that let a user manage their content and snippet library without leaving their usual environment. Candidates are a VS Code extension or a JetBrains plugin; the TUI is tracked separately below. Before building anything new, evaluate whether extending an existing tool in this space is a better use of effort than duplicating config-sync mechanics that are already solved, so the focus stays on the snippet library and composition workflow that is not well covered elsewhere.
+
 ### TUI (terminal user interface)
 
 Deferred branch. Not needed to make the CLI read well, which it already does;
@@ -527,10 +432,6 @@ own library one at a time from inside the TUI.
 - [ ] Revisit once the TUI itself exists, since this is an additional TUI-only
   caller of the library machinery, not a reason to build the TUI sooner.
 
-### Third-party integrations
-
-- [ ] Research and, where practical, build integrations that let a user manage their content and snippet library without leaving their usual environment. Candidates are a VS Code extension or a JetBrains plugin; the TUI is tracked separately above. Before building anything new, evaluate whether extending an existing tool in this space is a better use of effort than duplicating config-sync mechanics that are already solved, so the focus stays on the snippet library and composition workflow that is not well covered elsewhere.
-
 ### Additional language implementations
 
 - [ ] Once v1 behavior is stable and [`docs/core-contract.md`](docs/core-contract.md) is complete, port the CLI to one or more additional languages. Node.js/TypeScript, Go and Rust are the likely candidates. Broader than the zero-install binary below: this is about giving people who prefer not to touch Python a native option, not only about removing a runtime dependency. The contract exists so a port reimplements a specification rather than translating Python.
@@ -539,10 +440,6 @@ own library one at a time from inside the TUI.
 
 - [ ] Once behavior and file formats are stable, evaluate a zero-install path so end users need no Python. Candidates are PyInstaller or Nuitka, both trading binary size for no runtime dependency. If a port lands in Go or Rust, prefer shipping the binary from that instead: smaller static binaries, better cross-compilation, and a natural fit for Homebrew, Scoop, WinGet or an install script.
 
-### Final naming verification before public release
-
-- [ ] `mdcompose` was checked by search only. Before claiming it, run the exact checks: confirm `https://pypi.org/project/mdcompose/` returns 404, confirm `npm view mdcompose` errors, and register the GitHub repository before someone else does.
-
 ### Competitive landscape follow-up
 
 - [ ] Periodically revisit how the tools listed above evolve, to confirm this project's differentiation stays genuine rather than duplicated.

{mdcompose-0.1.3 → mdcompose-0.2.0}/docs/concepts.md

@@ -39,6 +39,28 @@ No substitution syntax is reserved either, deliberately -- a snippet containing
 The library itself is a flat directory of these files -- no index, no cache, no database.
 mdcompose never writes anything else into it and never touches an entry it did not create (a `.git` directory, a stray subdirectory, a file with another extension), which is what lets you keep the library under version control without the tool fighting you.
 
+## Skill frontmatter
+
+A skill is a second library, entirely separate from the snippet library, in the same format: one markdown file per skill, optional YAML frontmatter then body, filename minus `.md` as the id.
+Configured the same way too -- `skill_library_path` in the global config, defaulting to a `skills` sibling of the snippet library's own default directory.
+
+| Field | Type | Meaning |
+| ----- | ---- | ------- |
+| `title` | string | shown to a person; the id is used when absent |
+| `description` | string | one line of help, and what becomes the composed file's frontmatter description |
+| `tags` | list of strings | for filtering |
+| `stack_signals` | list of strings | filenames suggesting relevance |
+| `category` | string | a grouping label in the picker |
+
+There is no `applies_to` and no `order`: a skill is never split between AGENTS.md and CLAUDE.md the way a snippet can be, and its body is never concatenated with another skill's the way several snippet bodies share one block, so neither field has anything to do.
+
+`init` offers the skill library as a second, independently optional checkbox picker alongside the snippet picker.
+Each selected skill becomes its own file at `.claude/skills/<id>/SKILL.md`: generated `name`/`description` frontmatter first, then a managed block holding the skill's body, hashed and drift-checked the same way AGENTS.md's block is.
+The frontmatter is regenerated from the library on every run, even when only the description changed and the block's content did not -- unlike a managed block's surroundings, it is not content mdcompose leaves alone, since Claude Code needs it to track the library, not a stale copy.
+
+Deselecting a skill deletes its file outright, and its now-empty `.claude/skills/<id>/` directory with it, rather than leaving an empty block the way AGENTS.md would: an empty `SKILL.md` means nothing to a skill-loading agent.
+An empty or unconfigured skill library never blocks `init`, and the reverse holds too -- an empty snippet library does not stop skills from composing.
+
 ## Drift detection: normalization and hashing
 
 A managed block's hash has to mean the same thing on Windows, under WSL, and on Linux, or a committed lock file could never be trusted across a team.
@@ -129,17 +151,14 @@ None of them do these, which is the actual reason to reach for mdcompose instead
   Composing from a repository already means trusting its authors the way you trust their build scripts; mdcompose adds no second channel on top of that.
 - **Every interactive prompt has a flag.** Nothing here requires a human at a keyboard: `init --reapply`, `import --save-as-snippet`, and their siblings mean every command that can prompt can also run unattended, with the exit code contract above making the result scriptable in CI.
 
-One more, planned rather than shipped: none of the three alternatives above appear to be aiming past agent *instructions*.
-A skill file (Claude Code Skills, or whatever equivalent another tool adds) is already snippet-shaped -- frontmatter, a body, sometimes a script alongside it -- so composing those the same way is a natural extension of the same idea, not a new mechanism.
-It is flagged here rather than claimed as a feature; see Planned below.
+One more: none of the three alternatives above appear to be aiming past agent *instructions*.
+A skill file (Claude Code Skills, or whatever equivalent another tool adds) is snippet-shaped -- frontmatter, then a body -- so mdcompose composes those the same way it composes AGENTS.md and CLAUDE.md, as a second, independent library; see Skill frontmatter above.
+A skill bundled with an accompanying script is not yet supported, since the library and manifest model here is single-file-per-item throughout.
 
 ## Planned
 
 Larger efforts, tracked in [TODO.md](../TODO.md) under Roadmap, not needed for `0.1.0` and not yet built:
 
-- **Composing agent skills, not just AGENTS.md and CLAUDE.md.** A skill file (Claude Code Skills, or an equivalent another tool adds) is already snippet-shaped, so extending composition to skills would let a personal library of them be curated per project instead of an agent loading every skill unconditionally.
-  Fewer unneeded skills loaded is context an agent never has to spend, which makes this a token-efficiency argument, not only an organizational one.
-  Not scoped: a second composed-file family has to prove it reuses the existing core rather than forking it, the same bar every item below has to clear.
 - **A TUI**, likely on Textual, as a second adapter over the same core: browse and filter the library, tick snippets for a project, see per-file drift, review a diff before writing.
   The CLI stays the interface that has to work unattended -- exit codes, the stdout/stderr split, `--json`, `--quiet` are CLI concepts with no TUI equivalent, so the TUI is additive, never the only way to do something.
 - **A shared, browsable community snippet library, gated behind the TUI.** Concept borrowed from the skill marketplaces appearing around Claude Code Skills: a public GitHub repository as the source, crawled and indexed through GitHub's API into a locally cached, fuzzy-searchable list of community-contributed snippets, browsed and pulled into your own library one at a time from inside the TUI.