From 06f7e68fa4eeeb9014d7ee7b73f4b386d67c36c0 Mon Sep 17 00:00:00 2001 From: C-3PO Date: Tue, 30 Jun 2026 16:19:32 +0200 Subject: [PATCH 1/2] docs: keep refhub api key out of chat --- README.md | 29 +++++++++++++++++++++++++++++ SKILL.md | 7 ++++--- 2 files changed, 33 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 1000109..4fbaa32 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,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='rhk_REPLACE_ME' +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 skill and `@refhub/cli` pick up `REFHUB_API_KEY` from the environment, not from chat. + ## Use Invoke the skill from Codex: diff --git a/SKILL.md b/SKILL.md index 71b51e1..c4da944 100644 --- a/SKILL.md +++ b/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 From 739c744c4bd52e98e79f56a2561e08a8843bf2a9 Mon Sep 17 00:00:00 2001 From: C-3PO Date: Tue, 30 Jun 2026 19:47:27 +0200 Subject: [PATCH 2/2] feat: package RefHub as a Codex plugin --- .agents/plugins/marketplace.json | 20 +++++++ .codex-plugin/plugin.json | 29 ++++++++++ README.md | 42 ++++++++++++-- skills/refhub-codex/SKILL.md | 76 ++++++++++++++++++++++++++ skills/refhub-codex/agents/openai.yaml | 4 ++ 5 files changed, 165 insertions(+), 6 deletions(-) create mode 100644 .agents/plugins/marketplace.json create mode 100644 .codex-plugin/plugin.json create mode 100644 skills/refhub-codex/SKILL.md create mode 100644 skills/refhub-codex/agents/openai.yaml diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 0000000..e322035 --- /dev/null +++ b/.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" + } + ] +} diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json new file mode 100644 index 0000000..9f227ad --- /dev/null +++ b/.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" + } +} diff --git a/README.md b/README.md index 4fbaa32..03d27c0 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,33 @@ 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 add the marketplace: + +```sh +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: @@ -12,11 +38,11 @@ Install the RefHub CLI first: npm install -g @refhub/cli ``` -Then install or copy this skill into Codex's skills directory: +Then copy the skill into Codex's user skill directory: ```sh -mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills" -cp -R refhub-codex "${CODEX_HOME:-$HOME/.codex}/skills/refhub-codex" +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: @@ -34,7 +60,7 @@ Recommended pattern: keep the key in a local env file and launch Codex through a ```sh mkdir -p ~/.config/refhub cat > ~/.config/refhub/env <<'EOF' -export REFHUB_API_KEY='rhk_REPLACE_ME' +export REFHUB_API_KEY='REPLACE_WITH_REFHUB_API_KEY' EOF chmod 600 ~/.config/refhub/env ``` @@ -52,7 +78,7 @@ EOF chmod +x ~/.local/bin/codex-refhub ``` -Then start Codex with `codex-refhub`. The skill and `@refhub/cli` pick up `REFHUB_API_KEY` from the environment, not from chat. +Then start Codex with `codex-refhub`. The plugin/skill and `@refhub/cli` pick up `REFHUB_API_KEY` from the environment, not from chat. ## Use @@ -69,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 diff --git a/skills/refhub-codex/SKILL.md b/skills/refhub-codex/SKILL.md new file mode 100644 index 0000000..d078987 --- /dev/null +++ b/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__ +``` + +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 --item --file `. + +## 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 +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 diff --git a/skills/refhub-codex/agents/openai.yaml b/skills/refhub-codex/agents/openai.yaml new file mode 100644 index 0000000..8322eb1 --- /dev/null +++ b/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."