Fix public evidence metadata and install docs

Pengu-ai · Pengu-ai · commit 47a848776344 · 2026-06-05T22:14:34.000+08:00
diff --git a/.gitignore b/.gitignore
@@ -2,6 +2,7 @@
 __pycache__/
 *.pyc
 .pytest_cache/
+.codex/
 dist/
 build/
 *.egg-info/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.2.1 - 2026-06-05
+
+- Fixed README install instructions to point at the public GitHub repository before PyPI publication.
+- Renamed the GitHub issue counter field to `open_issues_and_prs_count` to avoid implying issue-only semantics.
+- Normalized release metadata in JSON output instead of storing full GitHub release API payloads.
+- Refreshed self-dogfood evidence after public issues and release creation.
+- Replaced version-specific generated launch-plan text with next-release wording.
+
 ## 0.2.0 - 2026-06-05
 
 - Added optional GitHub enrichment through `gh` for stars, forks, open issues, merged PRs, closed issues, releases, license, branch, and push metadata.
diff --git a/README.md b/README.md
@@ -16,11 +16,13 @@ The tool is intentionally conservative. It does not invent adoption, stars, down
 
 ## Install
 
+Install from GitHub:
+
 ```bash
-python -m pip install codex-oss-maintainer-kit
+python -m pip install "git+https://github.com/Pengu-ai/codex-oss-maintainer-kit.git"
 ```
 
-For local development:
+For local development from a clone:
 
 ```bash
 python -m venv .venv
diff --git a/docs/codex-for-oss-application-playbook.md b/docs/codex-for-oss-application-playbook.md
@@ -41,7 +41,7 @@ Use this structure:
 
 ## 30-Day Launch Milestones
 
-- Week 1: publish v0.1.0, README, license, examples, and issue templates.
+- Week 1: publish the first release, README, license, examples, and issue templates.
 - Week 2: dogfood on real repos and publish packet examples.
 - Week 3: invite maintainer feedback and merge first external contribution.
 - Week 4: cut v0.2.0 with GitHub API enrichment or package registry evidence.
diff --git a/docs/examples/demo-maintainer-packet.md b/docs/examples/demo-maintainer-packet.md
@@ -91,7 +91,7 @@ TODO: Replace with a 500-character plan for PR review, issue triage, release wor
 ## 30-Day Public Launch Plan
 
 - Publish the repository with an MIT license, clear README, examples, and issue templates.
-- Cut v0.1.0 and create a changelog entry.
+- Cut the next release and create a changelog entry.
 - Dogfood the CLI on 3-5 real public repositories with maintainer permission.
 - Open good-first-issue tasks for parser support, GitHub API enrichment, and docs examples.
 - Collect adoption evidence without artificial stars or misleading claims.
diff --git a/docs/examples/demo-profile.json b/docs/examples/demo-profile.json
@@ -30,7 +30,7 @@
     "repo_html_url": "https://github.com/example/demo-maintainer-project",
     "stars": 128,
     "forks": 17,
-    "open_issues": 6,
+    "open_issues_and_prs_count": 6,
     "default_branch": "main",
     "pushed_at": "2026-06-05T02:00:00Z",
     "license_spdx_id": "MIT",
diff --git a/docs/self-maintainer-packet.md b/docs/self-maintainer-packet.md
@@ -13,8 +13,9 @@ Generated: 2026-06-05
 
 ## Active Maintenance Evidence
 
-- Recent commits found: 5
+- Recent commits found: 6
 - Recent commit examples:
+  - b3520ce 2026-06-05 Pengu-ai Record public GitHub self evidence
   - dac75fe 2026-06-05 Pengu-ai Set public GitHub project URLs
   - 6dda12c 2026-06-05 Pengu-ai Refresh self dogfood packet
   - 7675610 2026-06-05 Pengu-ai Add GitHub enrichment and JSON examples
@@ -52,20 +53,22 @@ Generated: 2026-06-05
   - src/codex_oss_maintainer_kit/serialize.py
   - tests/test_cli.py
 - Contributors observed in Git history:
-  - 5	Pengu-ai
+  - 6	Pengu-ai
 
 ## GitHub Public Signals
 
 - GitHub repository: https://github.com/Pengu-ai/codex-oss-maintainer-kit
 - Stars: 0
 - Forks: 0
-- Open issues/PRs counter: 0
+- Open issues/PRs counter: 3
 - GitHub default branch: `main`
-- Last pushed at: 2026-06-05T04:20:49Z
+- Last pushed at: 2026-06-05T04:22:39Z
 - License: MIT
 - Merged pull requests in window: 0
 - Closed issues in window: 0
-- Recent releases found: 0
+- Recent releases found: 1
+- Recent releases:
+  - v0.2.0: v0.2.0 - GitHub enrichment and JSON examples (2026-06-05T04:22:39Z) - https://github.com/Pengu-ai/codex-oss-maintainer-kit/releases/tag/v0.2.0
 
 ## Maintainer Workload
 
@@ -109,7 +112,7 @@ TODO: Replace with a 500-character plan for PR review, issue triage, release wor
 ## 30-Day Public Launch Plan
 
 - Publish the repository with an MIT license, clear README, examples, and issue templates.
-- Cut v0.1.0 and create a changelog entry.
+- Cut the next release and create a changelog entry.
 - Dogfood the CLI on 3-5 real public repositories with maintainer permission.
 - Open good-first-issue tasks for parser support, GitHub API enrichment, and docs examples.
 - Collect adoption evidence without artificial stars or misleading claims.
diff --git a/docs/self-profile.json b/docs/self-profile.json
@@ -6,16 +6,17 @@
   "branch": "main",
   "latest_tag": null,
   "activity_window_days": 90,
-  "commit_count": 5,
+  "commit_count": 6,
   "recent_commits": [
+    "b3520ce 2026-06-05 Pengu-ai Record public GitHub self evidence",
     "dac75fe 2026-06-05 Pengu-ai Set public GitHub project URLs",
     "6dda12c 2026-06-05 Pengu-ai Refresh self dogfood packet",
     "7675610 2026-06-05 Pengu-ai Add GitHub enrichment and JSON examples",
     "2f6ac33 2026-06-05 Pengu-ai Add X post explainer card",
     "28ca5d5 2026-06-05 Pengu-ai Initial maintainer evidence kit"
   ],
   "contributors": [
-    "5\tPengu-ai"
+    "6\tPengu-ai"
   ],
   "changed_files": [
     ".github/ISSUE_TEMPLATE/bug_report.md",
@@ -55,13 +56,20 @@
     "repo_html_url": "https://github.com/Pengu-ai/codex-oss-maintainer-kit",
     "stars": 0,
     "forks": 0,
-    "open_issues": 0,
+    "open_issues_and_prs_count": 3,
     "default_branch": "main",
-    "pushed_at": "2026-06-05T04:20:49Z",
+    "pushed_at": "2026-06-05T04:22:39Z",
     "license_spdx_id": "MIT",
     "merged_pull_requests": [],
     "closed_issues": [],
-    "recent_releases": [],
+    "recent_releases": [
+      {
+        "tag_name": "v0.2.0",
+        "name": "v0.2.0 - GitHub enrichment and JSON examples",
+        "published_at": "2026-06-05T04:22:39Z",
+        "html_url": "https://github.com/Pengu-ai/codex-oss-maintainer-kit/releases/tag/v0.2.0"
+      }
+    ],
     "warnings": []
   }
 }
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codex-oss-maintainer-kit"
-version = "0.2.0"
+version = "0.2.1"
 description = "Generate maintainer evidence packets and Codex workflow plans for open-source projects."
 readme = "README.md"
 requires-python = ">=3.10"
diff --git a/src/codex_oss_maintainer_kit/__init__.py b/src/codex_oss_maintainer_kit/__init__.py
@@ -1,3 +1,3 @@
 """Tools for creating OSS maintainer evidence packets."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
diff --git a/src/codex_oss_maintainer_kit/demo.py b/src/codex_oss_maintainer_kit/demo.py
@@ -39,7 +39,7 @@ def build_demo_profile() -> RepoProfile:
             repo_html_url="https://github.com/example/demo-maintainer-project",
             stars=128,
             forks=17,
-            open_issues=6,
+            open_issues_and_prs_count=6,
             default_branch="main",
             pushed_at="2026-06-05T02:00:00Z",
             license_spdx_id="MIT",
diff --git a/src/codex_oss_maintainer_kit/github_inspector.py b/src/codex_oss_maintainer_kit/github_inspector.py
@@ -24,7 +24,7 @@ def collect_github_signals(
             repo_html_url=repo_url,
             stars=None,
             forks=None,
-            open_issues=None,
+            open_issues_and_prs_count=None,
             default_branch=None,
             pushed_at=None,
             license_spdx_id=None,
@@ -102,13 +102,13 @@ def collect_github_signals(
         repo_html_url=repo_payload.get("html_url") or f"https://github.com/{repo_full_name}",
         stars=_int_or_none(repo_payload.get("stargazers_count")),
         forks=_int_or_none(repo_payload.get("forks_count")),
-        open_issues=_int_or_none(repo_payload.get("open_issues_count")),
+        open_issues_and_prs_count=_int_or_none(repo_payload.get("open_issues_count")),
         default_branch=repo_payload.get("default_branch"),
         pushed_at=repo_payload.get("pushed_at"),
         license_spdx_id=license_info.get("spdx_id") if isinstance(license_info, dict) else None,
         merged_pull_requests=_list_of_dicts(prs_payload)[:12],
         closed_issues=_list_of_dicts(issues_payload)[:12],
-        recent_releases=_list_of_dicts(releases_payload)[:5],
+        recent_releases=_normalize_releases(_list_of_dicts(releases_payload))[:5],
         warnings=warnings,
     )
 
@@ -173,7 +173,7 @@ def _empty_signals(
         repo_html_url=repo_html_url,
         stars=None,
         forks=None,
-        open_issues=None,
+        open_issues_and_prs_count=None,
         default_branch=None,
         pushed_at=None,
         license_spdx_id=None,
@@ -194,3 +194,17 @@ def _list_of_dicts(value: object | None) -> list[dict[str, object]]:
     if not isinstance(value, list):
         return []
     return [item for item in value if isinstance(item, dict)]
+
+
+def _normalize_releases(items: list[dict[str, object]]) -> list[dict[str, object]]:
+    normalized = []
+    for item in items:
+        normalized.append(
+            {
+                "tag_name": item.get("tag_name"),
+                "name": item.get("name"),
+                "published_at": item.get("published_at"),
+                "html_url": item.get("html_url"),
+            }
+        )
+    return normalized
diff --git a/src/codex_oss_maintainer_kit/models.py b/src/codex_oss_maintainer_kit/models.py
@@ -12,7 +12,7 @@ class GitHubSignals:
     repo_html_url: str | None
     stars: int | None
     forks: int | None
-    open_issues: int | None
+    open_issues_and_prs_count: int | None
     default_branch: str | None
     pushed_at: str | None
     license_spdx_id: str | None
diff --git a/src/codex_oss_maintainer_kit/render.py b/src/codex_oss_maintainer_kit/render.py
@@ -80,7 +80,7 @@ def render_packet(profile: RepoProfile) -> str:
             "## 30-Day Public Launch Plan",
             "",
             "- Publish the repository with an MIT license, clear README, examples, and issue templates.",
-            "- Cut v0.1.0 and create a changelog entry.",
+            "- Cut the next release and create a changelog entry.",
             "- Dogfood the CLI on 3-5 real public repositories with maintainer permission.",
             "- Open good-first-issue tasks for parser support, GitHub API enrichment, and docs examples.",
             "- Collect adoption evidence without artificial stars or misleading claims.",
@@ -103,7 +103,7 @@ def _github_lines(github: GitHubSignals | None) -> list[str]:
         f"- GitHub repository: {github.repo_html_url or github.repo_full_name or 'Unknown'}",
         f"- Stars: {_value_or_todo(github.stars, 'TODO: add public adoption signal')}",
         f"- Forks: {_value_or_todo(github.forks, 'TODO: add public fork signal')}",
-        f"- Open issues/PRs counter: {_value_or_todo(github.open_issues, 'TODO: collect issue/PR count')}",
+        f"- Open issues/PRs counter: {_value_or_todo(github.open_issues_and_prs_count, 'TODO: collect issue/PR count')}",
         f"- GitHub default branch: `{github.default_branch or 'Unknown'}`",
         f"- Last pushed at: {github.pushed_at or 'Unknown'}",
         f"- License: {github.license_spdx_id or 'Unknown'}",
diff --git a/tests/test_github_inspector.py b/tests/test_github_inspector.py
@@ -42,10 +42,14 @@ def runner(args: list[str]) -> subprocess.CompletedProcess[str]:
         assert signals is not None
         self.assertEqual(signals.stars, 42)
         self.assertEqual(signals.forks, 7)
-        self.assertEqual(signals.open_issues, 3)
+        self.assertEqual(signals.open_issues_and_prs_count, 3)
         self.assertEqual(len(signals.merged_pull_requests), 1)
         self.assertEqual(len(signals.closed_issues), 1)
         self.assertEqual(len(signals.recent_releases), 1)
+        self.assertEqual(
+            set(signals.recent_releases[0]),
+            {"tag_name", "name", "published_at", "html_url"},
+        )
 
 
 if __name__ == "__main__":
diff --git a/tests/test_serialize.py b/tests/test_serialize.py
@@ -27,7 +27,7 @@ def test_render_json_serializes_dates_paths_and_github_signals(self) -> None:
                 repo_html_url="https://github.com/owner/repo",
                 stars=1,
                 forks=2,
-                open_issues=3,
+                open_issues_and_prs_count=3,
                 default_branch="main",
                 pushed_at="2026-06-05T00:00:00Z",
                 license_spdx_id="MIT",

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`"""Tools for creating OSS maintainer evidence packets."""`
`2`	`2`
`3`		`-__version__ = "0.2.0"`
	`3`	`+__version__ = "0.2.1"`