feat: package RefHub as a Codex plugin

.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "refhub-codex",
+  "interface": {
+    "displayName": "RefHub Codex"
+  },
+  "plugins": [
+    {
+      "name": "refhub-codex",
+      "source": {
+        "source": "local",
+        "path": "./"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_USE"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

.codex-plugin/plugin.json

@@ -0,0 +1,29 @@
+{
+  "name": "refhub-codex",
+  "version": "1.0.0",
+  "description": "Operate RefHub through its public API and CLI from Codex.",
+  "author": {
+    "name": "refhub-io",
+    "url": "https://github.com/refhub-io"
+  },
+  "homepage": "https://github.com/refhub-io/refhub-codex",
+  "repository": "https://github.com/refhub-io/refhub-codex",
+  "license": "MIT",
+  "keywords": ["refhub", "references", "research", "codex", "api"],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "RefHub Codex",
+    "shortDescription": "Operate RefHub through the public API.",
+    "longDescription": "Search, read, import, export, audit, enrich, and update RefHub vault content from Codex using @refhub/cli and scoped RefHub API keys.",
+    "developerName": "refhub-io",
+    "category": "Productivity",
+    "capabilities": ["Read", "Write"],
+    "websiteURL": "https://refhub.io",
+    "defaultPrompt": [
+      "Search my RefHub vault for graph layout papers.",
+      "Import a BibTeX entry into my RefHub vault.",
+      "Enrich RefHub items with Semantic Scholar metadata."
+    ],
+    "brandColor": "#2563EB"
+  }
+}

README.md

@@ -4,19 +4,45 @@ Codex-native RefHub skill packaging.
 
 This repo keeps RefHub's Codex integration separate from the Claude Code plugin marketplace. The skill uses `@refhub/cli` as its execution layer and describes the current RefHub public API contract for agent workflows.
 
-## Install
+## Install As A Codex Plugin
+
+This is the preferred distribution path for other Codex users. It follows OpenAI's current plugin packaging model: this repo contains a `.codex-plugin/plugin.json` manifest, a repo marketplace at `.agents/plugins/marketplace.json`, and the RefHub skill under `skills/refhub-codex/`.
 
 Install the RefHub CLI first:
 
 ```sh
 npm install -g @refhub/cli
 ```
 
-Then install or copy this skill into Codex's skills directory:
+Then add the marketplace:
 
 ```sh
-mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
-cp -R refhub-codex "${CODEX_HOME:-$HOME/.codex}/skills/refhub-codex"
+codex plugin marketplace add https://github.com/refhub-io/refhub-codex.git
+```
+
+Open the plugin directory and install **RefHub Codex** from the `refhub-codex` marketplace:
+
+```text
+/plugins
+```
+
+After installation, start a new Codex thread and invoke the plugin or skill with `@refhub-codex` / `$refhub-codex`.
+
+## Install As A Local Skill
+
+Use this path while iterating locally or when plugin support is not available in your Codex build.
+
+Install the RefHub CLI first:
+
+```sh
+npm install -g @refhub/cli
+```
+
+Then copy the skill into Codex's user skill directory:
+
+```sh
+mkdir -p "$HOME/.agents/skills/refhub-codex"
+cp -R skills/refhub-codex/. "$HOME/.agents/skills/refhub-codex/"
 ```
 
 Set an API key for normal data workflows:
@@ -25,6 +51,35 @@ Set an API key for normal data workflows:
 export REFHUB_API_KEY="rhk_..."
 ```
 
+Do not paste live API keys into Codex chat. Load them from the shell environment instead.
+
+## Secret Injection
+
+Recommended pattern: keep the key in a local env file and launch Codex through a wrapper.
+
+```sh
+mkdir -p ~/.config/refhub
+cat > ~/.config/refhub/env <<'EOF'
+export REFHUB_API_KEY='REPLACE_WITH_REFHUB_API_KEY'
+EOF
+chmod 600 ~/.config/refhub/env
+```
+
+Optional wrapper:
+
+```sh
+mkdir -p ~/.local/bin
+cat > ~/.local/bin/codex-refhub <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+source "$HOME/.config/refhub/env"
+exec codex "$@"
+EOF
+chmod +x ~/.local/bin/codex-refhub
+```
+
+Then start Codex with `codex-refhub`. The plugin/skill and `@refhub/cli` pick up `REFHUB_API_KEY` from the environment, not from chat.
+
 ## Use
 
 Invoke the skill from Codex:
@@ -40,9 +95,13 @@ Account setup/admin workflows such as API-key creation, Google Drive connect/dis
 ## Layout
 
 ```text
+.codex-plugin/plugin.json
+.agents/plugins/marketplace.json
 SKILL.md
 agents/openai.yaml
 references/refhub-api-contract.md
+skills/refhub-codex/SKILL.md
+skills/refhub-codex/agents/openai.yaml
 ```
 
 ## Related

SKILL.md

@@ -17,9 +17,10 @@ refhub --help
 ```
 
 2. Use `REFHUB_API_KEY` from the environment. A one-off `--api-key` flag may override it.
-3. Resolve vault IDs with `refhub vaults list` before operating on a vault. Do not infer IDs from names.
-4. Prefer JSON output for downstream reasoning. Use `--table` only for human-facing summaries.
-5. For unsupported account setup tasks, ask the user to use the RefHub web app.
+3. Keep the key out of chat history. Prefer loading `REFHUB_API_KEY` from a local shell env file or wrapper script before starting Codex.
+4. Resolve vault IDs with `refhub vaults list` before operating on a vault. Do not infer IDs from names.
+5. Prefer JSON output for downstream reasoning. Use `--table` only for human-facing summaries.
+6. For unsupported account setup tasks, ask the user to use the RefHub web app.
 
 ## Authentication Rules
 

skills/refhub-codex/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: refhub-codex
+description: Use when Codex needs to operate RefHub through its public API or CLI: search/read vaults, manage vault items, import DOI/BibTeX/URL records, export vaults, audit vault activity, enrich metadata through Semantic Scholar, or upload item PDFs including large API-key resumable Google Drive uploads.
+---
+
+# RefHub Codex
+
+Use the `refhub` CLI whenever it is available. It is the execution layer for RefHub API-key workflows and keeps authentication, request formatting, and errors consistent.
+
+## Quick Start
+
+1. Check for the CLI:
+
+```bash
+which refhub
+refhub --help
+```
+
+2. Use `REFHUB_API_KEY` from the environment. A one-off `--api-key` flag may override it.
+3. Keep the key out of chat history. Prefer loading `REFHUB_API_KEY` from a local shell env file or wrapper script before starting Codex.
+4. Resolve vault IDs with `refhub vaults list` before operating on a vault. Do not infer IDs from names.
+5. Prefer JSON output for downstream reasoning. Use `--table` only for human-facing summaries.
+6. For unsupported account setup tasks, ask the user to use the RefHub web app.
+
+## Authentication Rules
+
+Normal Codex workflows use RefHub API keys:
+
+```text
+Authorization: Bearer rhk_<publicId>_<secret>
+```
+
+API keys cover vault, item, tag, relation, import, search, export, vault audit, Semantic Scholar, and item PDF upload routes.
+
+Do not send API keys to browser/session management routes. API-key lifecycle, Google Drive connect/disconnect, legacy publication-level PDF upload, and global audit are session-JWT or web-app workflows.
+
+If credentials are missing, insufficient, or vault-restricted, stop and report the missing key/scope/vault access. Do not try adjacent routes to bypass scope.
+
+## Common Workflows
+
+- Search or read a vault: list vaults, resolve the vault ID, then use vault/item search commands.
+- Add or update items: ensure the key has `vaults:write`; tag IDs must already exist.
+- Delete a vault or item: warn that deletion is hard delete/no undo, and require explicit user confirmation before proceeding.
+- Import records: use DOI, BibTeX, or URL import commands when the vault is known and writable.
+- Export a vault: require `vaults:export`; export JSON or BibTeX as requested.
+- Audit a vault: use vault-scoped audit with an API key. Global audit is not an API-key workflow.
+- Enrich metadata: use `refhub discover` and `refhub enrich`; respect Semantic Scholar rate limits and avoid overwriting user-provided fields.
+- Upload item PDFs: use `refhub pdf upload --vault <vaultId> --item <itemId> --file <path.pdf>`.
+
+## PDF Upload Contract
+
+Small item PDFs use the raw API-key route:
+
+```text
+POST /api/v1/vaults/:vaultId/items/:itemId/pdf
+```
+
+Large vault-item PDFs use the API-key resumable flow:
+
+```text
+POST /api/v1/vaults/:vaultId/items/:itemId/pdf/session
+PUT <upload_url returned by Google Drive>
+POST /api/v1/vaults/:vaultId/items/:itemId/pdf/complete
+```
+
+Browser/session upload routes stay under `/api/v1/google-drive/...`. Do not point Codex/API-key workflows at those routes.
+
+## When More Detail Is Needed
+
+Read `../../references/refhub-api-contract.md` before:
+
+- calling HTTP routes directly instead of the CLI
+- handling permission errors or auth-mode confusion
+- implementing or reviewing RefHub agent integrations
+- reasoning about large PDF upload behavior
+- checking whether a workflow is supported by the current public API

skills/refhub-codex/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "RefHub Codex"
+  short_description: "Operate RefHub through the public API"
+  default_prompt: "Use $refhub-codex to search a RefHub vault and summarize the matching papers."