chore: publish codex marketplace package

.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "agentgram",
+  "interface": {
+    "displayName": "Agentgram"
+  },
+  "plugins": [
+    {
+      "name": "agentgram",
+      "source": {
+        "source": "local",
+        "path": "./plugins/agentgram"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

README.md

@@ -79,6 +79,17 @@ 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.
 
+To install Agentgram from the public Codex marketplace file in this repository:
+
+```sh
+codex plugin marketplace add jerryfane/agentgram --ref main
+codex plugin add agentgram@agentgram
+```
+
+Start a new Codex thread after installing so the Agentgram skill is loaded.
+Use `codex plugin marketplace upgrade agentgram` before reinstalling when you
+want newer Agentgram releases.
+
 When a user asks an agent to send a Telegram message, the agent should:
 
 1. Run `agentgram doctor`, or `bin/agentgram doctor` only from this repository

docs/release-checklist.md

@@ -10,6 +10,7 @@ Use this checklist before tagging or announcing an Agentgram release.
 - 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 no Telegram tokens, chat ids, generated plugin packages, logs, caches,
   or local session files are staged.
 
@@ -27,6 +28,18 @@ bin/agentgram doctor
 `doctor` may fail until `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` are set; it
 should fail clearly without printing secret values.
 
+## Codex Marketplace Smoke
+
+After merging the release, verify Codex can discover the marketplace:
+
+```sh
+codex plugin marketplace add jerryfane/agentgram --ref main
+codex plugin list
+codex plugin add agentgram@agentgram
+```
+
+Start a new Codex thread after installing so updated skills are loaded.
+
 ## Optional Live Telegram Smoke
 
 Only run this with explicit test credentials from the user:

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

@@ -0,0 +1,33 @@
+{
+  "name": "agentgram",
+  "version": "0.1.0",
+  "description": "Agent-neutral Telegram messaging helper for local coding agents.",
+  "author": {
+    "name": "Jerry Fane",
+    "url": "https://github.com/jerryfane"
+  },
+  "repository": "https://github.com/jerryfane/agentgram",
+  "license": "MIT",
+  "keywords": [
+    "telegram",
+    "agents",
+    "plugin",
+    "notifications",
+    "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.",
+    "developerName": "Jerry Fane",
+    "category": "Productivity",
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
+    "defaultPrompt": [
+      "Use Agentgram to send a Telegram message."
+    ]
+  }
+}

plugins/agentgram/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jerry Fane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plugins/agentgram/README.md

@@ -0,0 +1,131 @@
+# Agentgram
+
+Agentgram is an agent-neutral Telegram messaging helper. It lets Codex and
+other local coding 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.
+
+## Requirements
+
+- Python 3.12 or newer.
+- A Telegram bot token from BotFather.
+- A Telegram chat where the bot has been started or added.
+
+## Configuration
+
+Set secrets in your shell or agent runtime environment:
+
+```sh
+export TELEGRAM_BOT_TOKEN="123456:bot-token"
+export TELEGRAM_CHAT_ID="123456789"
+```
+
+Do not put real tokens in tracked files. `.env` and `.env.*` are ignored for
+local use, but environment variables are the preferred setup.
+
+For local setup templates, copy [.env.example](.env.example). It contains
+variable names only.
+
+## Usage
+
+Install from a git checkout, then put the CLI on your `PATH`:
+
+```sh
+git clone https://github.com/jerryfane/agentgram.git ~/.agentgram/agentgram
+mkdir -p ~/.local/bin
+ln -sf ~/.agentgram/agentgram/bin/agentgram ~/.local/bin/agentgram
+```
+
+Run the local CLI:
+
+```sh
+agentgram doctor
+agentgram send "deploy finished"
+agentgram send --silent --no-preview "quiet update"
+agentgram send --parse-mode HTML "<b>deploy finished</b>"
+```
+
+To discover a chat id, first send a message to the bot in Telegram, then run:
+
+```sh
+agentgram chat-id
+```
+
+For raw Telegram `getUpdates` output:
+
+```sh
+agentgram chat-id --raw
+```
+
+To check whether the local git checkout is current using existing local refs, or
+to update with a fast-forward-only pull:
+
+```sh
+agentgram update --check
+agentgram update
+```
+
+`agentgram update` refuses dirty worktrees, validates the checkout after pulling,
+and prints runtime-specific next steps when it can detect them. Codex plugin
+users should reinstall or refresh the plugin and start a new thread so updated
+skills are loaded.
+
+## Codex Plugin
+
+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.
+
+To install Agentgram from the public Codex marketplace file in this repository:
+
+```sh
+codex plugin marketplace add jerryfane/agentgram --ref main
+codex plugin add agentgram@agentgram
+```
+
+Start a new Codex thread after installing so the Agentgram skill is loaded.
+Use `codex plugin marketplace upgrade agentgram` before reinstalling when you
+want newer Agentgram releases.
+
+When a user asks an agent to send a Telegram message, the agent should:
+
+1. Run `agentgram doctor`, or `bin/agentgram doctor` only from this repository
+   checkout.
+2. Run `agentgram send "message"`, or `bin/agentgram send "message"` only from
+   this repository checkout, if setup is valid.
+3. Avoid direct Telegram API calls unless the user explicitly asks to bypass the
+   Agentgram CLI.
+
+## Troubleshooting
+
+- Bot was not started: open Telegram, send any message to the bot, then run
+  `agentgram chat-id` again.
+- Bad token: run `agentgram doctor`; malformed tokens fail locally, and revoked
+  or wrong tokens fail the Telegram `getMe` check.
+- Missing chat id: set `TELEGRAM_CHAT_ID`, or pass `--chat-id <id>` for a
+  one-off send after the user provides the target chat.
+- Forbidden chat: add the bot to the target chat or start a private chat with
+  it, then retry after confirming the chat id.
+- Telegram API errors: Agentgram prints Telegram's error description without the
+  bot token. Re-run `agentgram doctor` before retrying.
+
+## Release Checks
+
+Before release, run:
+
+```sh
+python3 -m unittest discover -s tests -v
+python3 scripts/validate_manifest.py
+git diff --check
+```
+
+See [docs/release-checklist.md](docs/release-checklist.md) for the full
+checklist and fresh-clone smoke.
+
+## Status
+
+Pre-release. CLI core, Codex skill packaging, update ergonomics, release docs,
+and CI checks are implemented.

plugins/agentgram/bin/agentgram

@@ -0,0 +1,17 @@
+#!/usr/bin/env python3
+"""Agentgram command entry point."""
+
+from pathlib import Path
+import sys
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / "src"
+if str(SRC) not in sys.path:
+    sys.path.insert(0, str(SRC))
+
+from agentgram.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

plugins/agentgram/skills/agentgram/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: agentgram
+description: Send explicit, user-requested Telegram messages from an agent session through the local Agentgram command-line tool.
+---
+
+# Agentgram
+
+Agentgram is a small Telegram messaging helper for agents. Use this skill when
+the user asks to send a Telegram message, verify Telegram messaging setup, find
+a chat id, or update the local Agentgram install.
+
+Before sending messages, prefer the installed `agentgram` command. If it is not
+on `PATH` and Agentgram is installed as a Codex plugin, resolve the plugin root
+from this skill file at `<plugin-root>/skills/agentgram/SKILL.md` and use
+`<plugin-root>/bin/agentgram` (`../../bin/agentgram` relative to this file). Use
+`./bin/agentgram` only after verifying the current checkout is Agentgram itself,
+with `.codex-plugin/plugin.json` name `agentgram` and
+`skills/agentgram/SKILL.md` present. In any other repository, report that
+Agentgram is not installed instead of running project-local fallback scripts or
+making an ad hoc Telegram API call.
+
+## Commands
+
+```sh
+agentgram send "message text"
+agentgram chat-id
+agentgram doctor
+agentgram update
+agentgram update --check
+```
+
+## Required Setup
+
+Agentgram reads:
+
+- `TELEGRAM_BOT_TOKEN`
+- `TELEGRAM_CHAT_ID`
+
+Secrets must come from environment variables or a user-owned local config file,
+never from tracked repository files, chat output, PR bodies, logs, or generated
+plugin packages.
+
+## Send Workflow
+
+1. Resolve the safe Agentgram command as `AGENTGRAM_CMD`: `agentgram` on
+   `PATH`, `<plugin-root>/bin/agentgram` from an installed Agentgram plugin, or
+   `./bin/agentgram` only from a verified Agentgram checkout.
+2. Run `$AGENTGRAM_CMD doctor` before sending, unless the user explicitly asks
+   for a best-effort send without preflight.
+3. If `doctor` only fails because `TELEGRAM_CHAT_ID` is missing and the user
+   provided the target chat id for this message, proceed with
+   `$AGENTGRAM_CMD send --chat-id <id>`.
+4. If `doctor` reports missing `TELEGRAM_CHAT_ID` and the user did not provide
+   a chat id, run `$AGENTGRAM_CMD chat-id` only after the user has messaged the
+   bot or added it to the target chat.
+5. Send only the exact user-requested message with `$AGENTGRAM_CMD send`.
+6. Use `--chat-id` only when the user provided a specific override for that
+   message.
+7. Use `--parse-mode HTML` or `--parse-mode MarkdownV2` only when the user asks
+   for formatted Telegram output or the message clearly requires it.
+
+Do not send automatic status updates merely because an agent task completed.
+Agentgram sends should be explicit and user-requested.
+
+## Update Workflow
+
+Use `$AGENTGRAM_CMD update --check` for a read-only status check on git-based
+installs. Use `$AGENTGRAM_CMD update` only when the user asks to update
+Agentgram. The update command refuses dirty git checkouts, runs
+`git pull --ff-only`, validates the local CLI/plugin files, and prints any Codex
+refresh instructions it can detect. For Codex marketplace installs, update with
+`codex plugin marketplace upgrade` and then reinstall `agentgram@agentgram`.

plugins/agentgram/src/agentgram/__init__.py

@@ -0,0 +1,5 @@
+"""Agentgram Telegram messaging helpers."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"