chore: improve Agentgram discoverability

.codex-plugin/plugin.json

@@ -1,27 +1,32 @@
 {
   "name": "agentgram",
-  "version": "0.1.0",
-  "description": "Agent-neutral Telegram messaging helper for local coding agents.",
+  "version": "0.1.1",
+  "description": "Codex and AI-agent Telegram messaging plugin with a local CLI.",
   "author": {
     "name": "Jerry Fane",
     "url": "https://github.com/jerryfane"
   },
   "repository": "https://github.com/jerryfane/agentgram",
   "license": "MIT",
   "keywords": [
-    "telegram",
-    "agents",
-    "plugin",
+    "ai-agents",
+    "codex",
+    "codex-plugin",
     "notifications",
-    "bot"
+    "telegram",
+    "telegram-bot"
   ],
   "skills": "./skills/",
   "interface": {
     "displayName": "Agentgram",
-    "shortDescription": "Send Telegram messages from agent sessions.",
-    "longDescription": "Agentgram helps coding agents send explicit, user-requested Telegram messages through the local Agentgram CLI and Telegram Bot API using a bot token and chat id from the user's environment.",
+    "shortDescription": "Send Telegram messages from Codex and agent sessions.",
+    "longDescription": "Agentgram is a Codex Telegram plugin and local CLI for AI agents. It sends explicit, user-requested Telegram messages through the Telegram Bot API using a bot token and chat id from the user's environment.",
     "developerName": "Jerry Fane",
     "category": "Productivity",
+    "websiteURL": "https://github.com/jerryfane/agentgram",
+    "brandColor": "#1F8A70",
+    "composerIcon": "assets/agentgram-logo.svg",
+    "logo": "assets/agentgram-logo.svg",
     "capabilities": [
       "Read",
       "Write"

.github/workflows/ci.yml

@@ -20,6 +20,16 @@ jobs:
         run: python3 -m unittest discover -s tests -v
       - name: Validate plugin manifest
         run: python3 scripts/validate_manifest.py
+      - name: Build Python package
+        run: |
+          python3 -m pip install --upgrade build
+          python3 -m build
+      - name: Smoke installed wheel
+        run: |
+          python3 -m venv /tmp/agentgram-wheel-smoke
+          /tmp/agentgram-wheel-smoke/bin/python -m pip install dist/*.whl
+          /tmp/agentgram-wheel-smoke/bin/agentgram --help
+          /tmp/agentgram-wheel-smoke/bin/agentgram doctor || true
       - name: Check whitespace
         env:
           BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}

.github/workflows/publish-pypi.yml

@@ -0,0 +1,26 @@
+name: Publish PyPI
+
+on:
+  release:
+    types:
+      - published
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build package
+        run: |
+          python3 -m pip install --upgrade build
+          python3 -m build
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -1,6 +1,7 @@
 .DS_Store
 *.pyc
 __pycache__/
+*.egg-info/
 .env
 .env.*
 !.env.example

README.md

@@ -1,13 +1,22 @@
 # Agentgram
 
-Agentgram is an agent-neutral Telegram messaging helper. It lets Codex and
-other local coding agents send explicit, user-requested Telegram messages
+[![CI](https://github.com/jerryfane/agentgram/actions/workflows/ci.yml/badge.svg)](https://github.com/jerryfane/agentgram/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/jerryfane/agentgram)](https://github.com/jerryfane/agentgram/releases)
+[![PyPI](https://img.shields.io/pypi/v/agentgram-tg)](https://pypi.org/project/agentgram-tg/)
+[![License](https://img.shields.io/github/license/jerryfane/agentgram)](LICENSE)
+
+Agentgram is a Codex Telegram plugin and agent-neutral messaging helper. It lets
+Codex and other local AI agents send explicit, user-requested Telegram messages
 through a Telegram bot token and chat id.
 
 Agentgram is intentionally local-first. It does not run a hosted service, and it
 does not send automatic completion notifications unless a future task explicitly
 adds that behavior.
 
+Use Agentgram when you want a Telegram notification plugin for AI agents, a
+simple way to send Telegram messages from Codex, or a reusable local CLI for
+agent messaging via a bot token.
+
 ## Requirements
 
 - Python 3.12 or newer.
@@ -31,7 +40,13 @@ variable names only.
 
 ## Usage
 
-Install from a git checkout, then put the CLI on your `PATH`:
+Install the released CLI from PyPI:
+
+```sh
+pipx install agentgram-tg
+```
+
+Or install from a git checkout, then put the CLI on your `PATH`:
 
 ```sh
 git clone https://github.com/jerryfane/agentgram.git ~/.agentgram/agentgram
@@ -77,7 +92,8 @@ skills are loaded.
 
 The Codex plugin skill lives in `skills/agentgram/SKILL.md`, with the plugin
 manifest at `.codex-plugin/plugin.json`. The skill tells Codex to use the local
-`agentgram` CLI as the execution path.
+`agentgram` CLI as the execution path. This repository also contains a public
+Codex marketplace file so Agentgram can be installed as a Codex Telegram plugin.
 
 To install Agentgram from the public Codex marketplace file in this repository:
 
@@ -127,5 +143,6 @@ checklist and fresh-clone smoke.
 
 ## Status
 
-Pre-release. CLI core, Codex skill packaging, update ergonomics, release docs,
-and CI checks are implemented.
+Released. Agentgram `v0.1.x` includes the Telegram CLI, Codex skill packaging,
+public Codex marketplace metadata, update ergonomics, release docs, and CI
+checks.

bin/agentgram

@@ -10,7 +10,7 @@ SRC = ROOT / "src"
 if str(SRC) not in sys.path:
     sys.path.insert(0, str(SRC))
 
-from agentgram.cli import main
+from agentgram_tg.cli import main
 
 
 if __name__ == "__main__":

docs/release-checklist.md

@@ -7,10 +7,15 @@ Use this checklist before tagging or announcing an Agentgram release.
 - Confirm the repository is clean with `git status --short`.
 - Run `python3 -m unittest discover -s tests -v`.
 - Run `python3 scripts/validate_manifest.py`.
+- Run `python3 -m build`.
+- Install the built wheel in a temporary virtual environment and run
+  `agentgram --help`.
 - Run `git diff --check`.
 - Run `bin/agentgram update --check` from the release checkout.
 - Verify `.env.example` contains variable names only.
 - Verify `.agents/plugins/marketplace.json` points at `./plugins/agentgram`.
+- Verify PyPI package metadata uses distribution name `agentgram-tg` and command
+  name `agentgram`.
 - Verify no Telegram tokens, chat ids, generated plugin packages, logs, caches,
   or local session files are staged.
 
@@ -21,6 +26,11 @@ git clone https://github.com/jerryfane/agentgram.git /tmp/agentgram-smoke
 cd /tmp/agentgram-smoke
 python3 -m unittest discover -s tests -v
 python3 scripts/validate_manifest.py
+python3 -m pip install --upgrade build
+python3 -m build
+python3 -m venv /tmp/agentgram-wheel-smoke
+/tmp/agentgram-wheel-smoke/bin/python -m pip install dist/*.whl
+/tmp/agentgram-wheel-smoke/bin/agentgram --help
 bin/agentgram --help
 bin/agentgram doctor
 ```
@@ -40,6 +50,16 @@ codex plugin add agentgram@agentgram
 
 Start a new Codex thread after installing so updated skills are loaded.
 
+## Discovery Smoke
+
+- Confirm GitHub topics include `codex-plugin`, `openai-codex`,
+  `telegram-bot`, `ai-agents`, `agent-tools`, `python`, `cli`, and
+  `notifications`.
+- Confirm the latest release notes mention both Codex install and
+  `pipx install agentgram-tg`.
+- Submit or refresh the community marketplace listing and awesome-list PR when
+  release metadata changes.
+
 ## Optional Live Telegram Smoke
 
 Only run this with explicit test credentials from the user:

plugins/agentgram/.codex-plugin/plugin.json

@@ -1,27 +1,32 @@
 {
   "name": "agentgram",
-  "version": "0.1.0",
-  "description": "Agent-neutral Telegram messaging helper for local coding agents.",
+  "version": "0.1.1",
+  "description": "Codex and AI-agent Telegram messaging plugin with a local CLI.",
   "author": {
     "name": "Jerry Fane",
     "url": "https://github.com/jerryfane"
   },
   "repository": "https://github.com/jerryfane/agentgram",
   "license": "MIT",
   "keywords": [
-    "telegram",
-    "agents",
-    "plugin",
+    "ai-agents",
+    "codex",
+    "codex-plugin",
     "notifications",
-    "bot"
+    "telegram",
+    "telegram-bot"
   ],
   "skills": "./skills/",
   "interface": {
     "displayName": "Agentgram",
-    "shortDescription": "Send Telegram messages from agent sessions.",
-    "longDescription": "Agentgram helps coding agents send explicit, user-requested Telegram messages through the local Agentgram CLI and Telegram Bot API using a bot token and chat id from the user's environment.",
+    "shortDescription": "Send Telegram messages from Codex and agent sessions.",
+    "longDescription": "Agentgram is a Codex Telegram plugin and local CLI for AI agents. It sends explicit, user-requested Telegram messages through the Telegram Bot API using a bot token and chat id from the user's environment.",
     "developerName": "Jerry Fane",
     "category": "Productivity",
+    "websiteURL": "https://github.com/jerryfane/agentgram",
+    "brandColor": "#1F8A70",
+    "composerIcon": "assets/agentgram-logo.svg",
+    "logo": "assets/agentgram-logo.svg",
     "capabilities": [
       "Read",
       "Write"

plugins/agentgram/README.md

@@ -1,13 +1,22 @@
 # Agentgram
 
-Agentgram is an agent-neutral Telegram messaging helper. It lets Codex and
-other local coding agents send explicit, user-requested Telegram messages
+[![CI](https://github.com/jerryfane/agentgram/actions/workflows/ci.yml/badge.svg)](https://github.com/jerryfane/agentgram/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/jerryfane/agentgram)](https://github.com/jerryfane/agentgram/releases)
+[![PyPI](https://img.shields.io/pypi/v/agentgram-tg)](https://pypi.org/project/agentgram-tg/)
+[![License](https://img.shields.io/github/license/jerryfane/agentgram)](LICENSE)
+
+Agentgram is a Codex Telegram plugin and agent-neutral messaging helper. It lets
+Codex and other local AI agents send explicit, user-requested Telegram messages
 through a Telegram bot token and chat id.
 
 Agentgram is intentionally local-first. It does not run a hosted service, and it
 does not send automatic completion notifications unless a future task explicitly
 adds that behavior.
 
+Use Agentgram when you want a Telegram notification plugin for AI agents, a
+simple way to send Telegram messages from Codex, or a reusable local CLI for
+agent messaging via a bot token.
+
 ## Requirements
 
 - Python 3.12 or newer.
@@ -31,7 +40,13 @@ variable names only.
 
 ## Usage
 
-Install from a git checkout, then put the CLI on your `PATH`:
+Install the released CLI from PyPI:
+
+```sh
+pipx install agentgram-tg
+```
+
+Or install from a git checkout, then put the CLI on your `PATH`:
 
 ```sh
 git clone https://github.com/jerryfane/agentgram.git ~/.agentgram/agentgram
@@ -77,7 +92,8 @@ skills are loaded.
 
 The Codex plugin skill lives in `skills/agentgram/SKILL.md`, with the plugin
 manifest at `.codex-plugin/plugin.json`. The skill tells Codex to use the local
-`agentgram` CLI as the execution path.
+`agentgram` CLI as the execution path. This repository also contains a public
+Codex marketplace file so Agentgram can be installed as a Codex Telegram plugin.
 
 To install Agentgram from the public Codex marketplace file in this repository:
 
@@ -127,5 +143,6 @@ checklist and fresh-clone smoke.
 
 ## Status
 
-Pre-release. CLI core, Codex skill packaging, update ergonomics, release docs,
-and CI checks are implemented.
+Released. Agentgram `v0.1.x` includes the Telegram CLI, Codex skill packaging,
+public Codex marketplace metadata, update ergonomics, release docs, and CI
+checks.

plugins/agentgram/bin/agentgram

@@ -10,7 +10,7 @@ SRC = ROOT / "src"
 if str(SRC) not in sys.path:
     sys.path.insert(0, str(SRC))
 
-from agentgram.cli import main
+from agentgram_tg.cli import main
 
 
 if __name__ == "__main__":

plugins/agentgram/src/agentgram/__init__.py → plugins/agentgram/src/agentgram_tg/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"

plugins/agentgram/src/agentgram/cli.py → plugins/agentgram/src/agentgram_tg/cli.py

@@ -20,6 +20,7 @@
 TOKEN_ENV = "TELEGRAM_BOT_TOKEN"
 CHAT_ID_ENV = "TELEGRAM_CHAT_ID"
 PLUGIN_NAME = "agentgram"
+PYTHON_PACKAGE = "agentgram_tg"
 
 
 class CliError(RuntimeError):
@@ -374,7 +375,7 @@ def validate_checkout(repo: Path) -> None:
         repo / "bin" / "agentgram",
         repo / ".codex-plugin" / "plugin.json",
         repo / "skills" / PLUGIN_NAME / "SKILL.md",
-        repo / "src" / PLUGIN_NAME / "cli.py",
+        repo / "src" / PYTHON_PACKAGE / "cli.py",
     ]
     missing = [str(path.relative_to(repo)) for path in required_files if not path.is_file()]
     if missing:

pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agentgram-tg"
+version = "0.1.1"
+description = "Telegram messaging CLI and Codex plugin for local AI agents."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [
+  { name = "Jerry Fane" }
+]
+keywords = [
+  "agentgram",
+  "ai-agents",
+  "codex",
+  "codex-plugin",
+  "notifications",
+  "telegram",
+  "telegram-bot"
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Communications :: Chat",
+  "Topic :: Software Development :: User Interfaces"
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/jerryfane/agentgram"
+Repository = "https://github.com/jerryfane/agentgram"
+Issues = "https://github.com/jerryfane/agentgram/issues"
+Changelog = "https://github.com/jerryfane/agentgram/releases"
+
+[project.scripts]
+agentgram = "agentgram_tg.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]