feat(publish): include README.md, CHANGELOG.md, and LICENSE in auto-pack archive

Matches npm behaviour of bundling standard root-level documentation files
when present. Matched case-insensitively; LICENSE has no required extension.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: nadav-y

src/apm_cli/commands/publish.py

@@ -186,6 +186,10 @@ def _resolve_registry_name(name: str | None, registries: dict[str, str]) -> str:
 def _pack_archive(project_root: Path, apm_yml_path: Path, pkg, logger, verbose: bool) -> Path:
     """Build a flat registry tarball (``apm.yml`` + ``.apm/`` at archive root).
 
+    Also includes ``README.md``, ``CHANGELOG.md``, and ``LICENSE`` (case-
+    insensitive, no extension required for LICENSE) when present — matching
+    npm's behaviour of bundling standard root-level documentation files.
+
     Registry servers and ``apm install`` expect the APM source layout at the
     tarball root — not the ``apm pack --archive`` plugin bundle wrapper
     (``{name}-{version}/plugin.json``). See registry HTTP API §6.
@@ -214,9 +218,22 @@ def _tar_filter(ti: tarfile.TarInfo) -> tarfile.TarInfo | None:
             return None
         return ti
 
+    # Standard root-level doc files included when present (npm parity).
+    # Matched case-insensitively; LICENSE has no required extension.
+    _DOC_CANDIDATES = ("README.md", "CHANGELOG.md", "LICENSE", "LICENCE")
+
     with tarfile.open(dest, mode="w:gz") as tar:
         tar.add(apm_yml_path, arcname="apm.yml", filter=_tar_filter, recursive=False)
         tar.add(apm_dir, arcname=".apm", filter=_tar_filter)
+        for candidate in _DOC_CANDIDATES:
+            # Case-insensitive match against actual filenames in project root.
+            match = next(
+                (f for f in project_root.iterdir()
+                 if f.is_file() and f.name.lower() == candidate.lower()),
+                None,
+            )
+            if match:
+                tar.add(match, arcname=match.name, filter=_tar_filter, recursive=False)
 
     return dest
 

tests/unit/commands/test_publish_registry_archive.py

@@ -56,6 +56,50 @@ def test_skips_appledouble_sidecars(self, tmp_path: Path) -> None:
         members = _list_tar_members(tarball.read_bytes())
         assert not any("._" in m for m in members)
 
+    def test_includes_readme_when_present(self, tmp_path: Path) -> None:
+        (tmp_path / "apm.yml").write_text(
+            "name: demo\nversion: 1.0.0\ndescription: x\nauthor: a\n",
+            encoding="utf-8",
+        )
+        (tmp_path / "README.md").write_text("# Demo\n", encoding="utf-8")
+        (tmp_path / ".apm" / "skills" / "demo").mkdir(parents=True)
+        (tmp_path / ".apm" / "skills" / "demo" / "SKILL.md").write_text("# s\n")
+
+        pkg = APMPackage(name="demo", version="1.0.0")
+        tarball = _pack_archive(tmp_path, tmp_path / "apm.yml", pkg, MagicMock(), verbose=False)
+        assert "README.md" in _list_tar_members(tarball.read_bytes())
+
+    def test_includes_changelog_and_license_when_present(self, tmp_path: Path) -> None:
+        (tmp_path / "apm.yml").write_text(
+            "name: demo\nversion: 1.0.0\ndescription: x\nauthor: a\n",
+            encoding="utf-8",
+        )
+        (tmp_path / "CHANGELOG.md").write_text("# Changelog\n", encoding="utf-8")
+        (tmp_path / "LICENSE").write_text("MIT\n", encoding="utf-8")
+        (tmp_path / ".apm" / "skills" / "demo").mkdir(parents=True)
+        (tmp_path / ".apm" / "skills" / "demo" / "SKILL.md").write_text("# s\n")
+
+        pkg = APMPackage(name="demo", version="1.0.0")
+        tarball = _pack_archive(tmp_path, tmp_path / "apm.yml", pkg, MagicMock(), verbose=False)
+        members = _list_tar_members(tarball.read_bytes())
+        assert "CHANGELOG.md" in members
+        assert "LICENSE" in members
+
+    def test_doc_files_absent_are_skipped(self, tmp_path: Path) -> None:
+        (tmp_path / "apm.yml").write_text(
+            "name: demo\nversion: 1.0.0\ndescription: x\nauthor: a\n",
+            encoding="utf-8",
+        )
+        (tmp_path / ".apm" / "skills" / "demo").mkdir(parents=True)
+        (tmp_path / ".apm" / "skills" / "demo" / "SKILL.md").write_text("# s\n")
+
+        pkg = APMPackage(name="demo", version="1.0.0")
+        tarball = _pack_archive(tmp_path, tmp_path / "apm.yml", pkg, MagicMock(), verbose=False)
+        members = _list_tar_members(tarball.read_bytes())
+        assert "README.md" not in members
+        assert "CHANGELOG.md" not in members
+        assert "LICENSE" not in members
+
     def test_missing_dot_apm_rejected(self, tmp_path: Path) -> None:
         (tmp_path / "apm.yml").write_text(
             "name: demo\nversion: 1.0.0\ndescription: x\nauthor: a\n",