AX-1987 - Change readme

CONTRIBUTING.md

@@ -1,41 +1,83 @@
-# Contributing to codex-plugin
+# Contributing to the JFrog Plugin for OpenAI Codex
 
-Thanks for your interest in contributing! This project is maintained by
-JFrog Ltd. and licensed under Apache-2.0 (see LICENSE).
+Thank you for your interest in contributing! This project is maintained by JFrog and licensed under the [Apache License 2.0](LICENSE).
 
-## Before you contribute
+## Contributor License Agreement (CLA)
 
-All contributors must sign the JFrog Contributor License Agreement
-(CLA) before a pull request can be merged: https://jfrog.com/cla/
+All contributors must sign the [JFrog CLA](https://jfrog.com/cla/) before contributions can be merged. A CLA check runs automatically on every pull request — follow the prompts to sign if you haven't already.
 
-The CLA check runs automatically on your first pull request — follow
-the bot's instructions to sign.
+## How to Contribute
 
-## How to contribute
+1. **Fork** the repository and create a feature branch from `main`.
+2. Make your changes, ensuring they follow the existing code style and project conventions.
+3. **Validate** locally:
 
-1. Fork the repository and create a branch from `main`.
-2. Make your change, including tests where applicable.
-3. Run the validation suite locally:
+```bash
+npm test         # unit tests for the manifest/skill validator
+npm run validate # lint the plugin manifests + skill frontmatter
+```
 
-   npm test
-   npm run validate
+1. **Test** by loading your clone as the plugin. The repo root is the marketplace root (`.agents/plugins/marketplace.json` registers the `jfrog` plugin):
 
-4. Open a pull request describing the change and why it's needed.
-5. A maintainer will review, request changes if needed, and merge once
-   CI and the CLA check pass.
+```bash
+codex plugin marketplace add /path/to/codex-plugin
+codex plugin add jfrog@codex-plugin
+```
 
-## Reporting issues
+Exercise the skills you changed, then browse installed plugins in the Codex TUI with `/plugins`.
 
-Open a GitHub issue with a clear description, reproduction steps (if
-applicable), and expected vs. actual behavior.
+1. **Commit** with a clear, descriptive message.
+2. Open a **pull request** against `main` with a summary of what changed and why.
 
-## Code of conduct
+### Updating the vendored skills
 
-Be respectful and constructive. Disruptive or abusive behavior may
-result in the contribution being rejected and further participation
-restricted.
+The `skills/` tree is vendored from [jfrog/jfrog-skills](https://github.com/jfrog/jfrog-skills) and committed to `main` — see [`VENDOR.md`](VENDOR.md) for the full flow. To regenerate the tree locally against the pin in [`scripts/sync-skills-vendor.json`](scripts/sync-skills-vendor.json):
 
-## Questions
+```bash
+node scripts/sync-skills.mjs
+```
 
-For questions about this project's OSS status or licensing, contact
-ossgov@jfrog.com.
+This downloads the pinned upstream tarball and replaces the contents of `skills/`. Commit the result alongside the pin bump and the matching version bump (see [Releasing](#releasing)).
+
+## Pre-release checklist
+
+- [ ] `npm test` and `npm run validate` pass.
+- [ ] `version` bumped and **identical** in both [`.codex-plugin/plugin.json`](.codex-plugin/plugin.json) and [`package.json`](package.json) (CI enforces the match).
+- [ ] No secrets, credentials, or API keys committed.
+- [ ] If the skill tree changed: `pin` in [`scripts/sync-skills-vendor.json`](scripts/sync-skills-vendor.json) matches the upstream tag the new tree was generated from, and the README Prerequisites link points at that tag.
+- [ ] Smoke-test: install locally with `codex plugin marketplace add /path/to/codex-plugin && codex plugin add jfrog@codex-plugin`.
+
+## Releasing
+
+To cut a release:
+
+1. In your PR, bump `version` in **both** [`.codex-plugin/plugin.json`](.codex-plugin/plugin.json) and [`package.json`](package.json) to the same, not-yet-released value. `plugin.json` is canonical; `package.json` carries its own copy, and the two are cross-checked.
+2. Merge to `main` with `[major]`, `[minor]`, or `[patch]` in the commit **subject** — the first line. A marker elsewhere in the body is ignored on purpose.
+
+The marker only decides *whether* to release; the version comes from the manifests either way, so the bump is reviewed in the PR that makes it. Merging a marker without bumping the manifests fails the release rather than re-tagging a shipped version.
+
+[`.github/workflows/release.yml`](.github/workflows/release.yml) reads the version from `.codex-plugin/plugin.json` (cross-checked against `package.json`), refuses to continue if that version is already tagged, re-runs the same validation as the PR workflow, packages the tracked files at `HEAD` (minus `.github/`) into `release.zip`, and creates the `vX.Y.Z` tag as part of publishing the GitHub Release.
+
+A PR without a marker (docs, chores, or fixes that don't ship a new plugin version) merges normally and cuts no release.
+
+## Reporting Issues
+
+Open a [GitHub issue](https://github.com/jfrog/codex-plugin/issues) with:
+
+- A clear title and description of the problem.
+- Steps to reproduce (if applicable).
+- Expected vs. actual behavior.
+
+## Code Guidelines
+
+- Keep changes focused — one logical change per PR.
+- Follow existing patterns and naming conventions in the codebase.
+- Do not commit secrets, credentials, or API keys.
+
+## Code of Conduct
+
+Be respectful and constructive. We are committed to providing a welcoming and inclusive experience for everyone.
+
+## Questions?
+
+For questions about this project's OSS status or licensing, contact ossgov@jfrog.com.

README.md

@@ -1,40 +1,205 @@
 # JFrog Plugin for OpenAI Codex
 
-Delivers the JFrog skills **and the JFrog MCP server** to OpenAI Codex.
+JFrog plugin for [OpenAI Codex](https://developers.openai.com/codex/): artifact
+management, security scanning, supply-chain best practices, and Agent Guard.
 
-## Install (git marketplace)
+## Features
 
+The JFrog plugin provides the following capabilities, grouped by component:
+
+| Component | Feature | Description |
+| --- | --- | --- |
+| **MCP** | JFrog MCP server | Bundled `jfrog` MCP server ([`.mcp.json`](.mcp.json)) at `https://<JFROG_PLATFORM_URL>/mcp`; this server signs in via OAuth (`codex mcp login jfrog`), so it needs no API key. |
+| **Skill** | JFrog Platform | Interact with Artifactory repositories, builds, permissions, users, access tokens, projects, release bundles, and platform administration via the JFrog CLI and REST/GraphQL APIs. Also covers security audits, CVE lookups, and Advanced Security exposure queries. |
+| **Skill** | Package safety & download | Check whether npm, Maven, PyPI, Go, and other packages are safe, curated, or allowed, then download them through Artifactory remote caches or curation-aware package managers. |
+| **Skill** | Agent Guard | Codex manages MCPs through the JFrog Agent Guard. Through the Agent Guard you can discover, install, configure, update, and remove MCP servers from the JFrog AI Catalog approved for your project, and authenticate to remote HTTP MCPs via OAuth, API key, or bearer token. |
+
+---
+
+## Prerequisites
+
+Before installing, make sure you have:
+
+- **JFrog host URL and access token** — Your JFrog platform URL and a valid access token.
+- **OpenAI Codex** — Installed, with plugin support (`codex plugin` CLI commands available).
+- **Node.js** (≥ 18) — with `npx` on your `PATH` (used by the Agent Guard).
+- **Skill runtime requirements** — `jf` CLI, `jq`, and `curl` on `PATH`, plus a configured JFrog instance. For the minimum versions, see the upstream skills [`Requirements`](https://github.com/jfrog/jfrog-skills/blob/v0.22.0/README.md#requirements). Configure the CLI with `jf config add` — see [Authentication](#authentication).
+- **JFrog AI Catalog** (optional) — If you want to use the Agent Guard feature, your JFrog subscription needs to include the AI Catalog entitlement. Contact your JFrog account team if you're unsure whether it's enabled.
+- **JFrog CLI ≥ 2.105.0** (optional) — If you want the Agent Guard to auto-resolve the credentials/server ID from the JFrog CLI configuration.
+- **JFrog project** (optional) — If you want to use the Agent Guard feature.
+
+---
+
+## Installation
+
+### Install the Codex plugin
+
+Add the JFrog marketplace and install the plugin with the Codex CLI:
+
+```bash
+codex plugin marketplace add jfrog/codex-plugin
+codex plugin add jfrog@codex-plugin
 ```
-/plugin marketplace add jfrog/codex-plugin
-/plugin install jfrog@codex-plugin
-/reload-plugins
+
+Browse installed plugins in the Codex TUI with `/plugins`.
+
+### Local development
+
+Test an uncommitted checkout without publishing. From (or pointing at) your clone
+— the repo root is the marketplace root; `.agents/plugins/marketplace.json`
+registers the `jfrog` plugin:
+
+```bash
+codex plugin marketplace add /path/to/codex-plugin
+codex plugin add jfrog@codex-plugin
 ```
 
-## MCP server
+---
+
+## Authentication
+
+Configure the JFrog CLI so the skills and Agent Guard can reach your platform. Run
+`jf login` for browser-based setup, or if you have never configured the JFrog CLI
+on this machine:
+
+1. Open your terminal.
+2. Run:
+
+   ```bash
+   jf config add
+   ```
+
+3. Follow the interactive prompts to enter your JFrog platform URL and access token.
+
+---
+
+## JFrog Platform MCP server
 
 The plugin bundles the `jfrog` MCP server ([`.mcp.json`](.mcp.json)). After
 installing, do two things:
 
 1. **Set your host.** Find the install path with `codex plugin list` (the
    `jfrog@codex-plugin` row) and edit `<PATH>/.mcp.json`. Replace
-   `<JFROG_PLATFORM_URL>` in the `url` with your full JFrog Platform host - e.g.
+   `<JFROG_PLATFORM_URL>` in the `url` with your full JFrog Platform host — e.g.
    `mycompany.jfrog.io` (or your self-hosted / custom domain).
 2. **Log in (OAuth).** Run `codex mcp login jfrog` and finish the browser
    sign-in.
 
-Restart Codex; `/mcp` now lists `jfrog` with its tools.
+Restart Codex; the `jfrog` MCP server and its tools are now available (verify with
+`codex mcp list`).
+
+---
+
+## Usage
+
+Once configured, interact with the JFrog plugin through natural language.
+Examples are grouped by capability.
+
+### JFrog Platform skill
 
-## Skills
+| Ask the agent… | What happens |
+| --- | --- |
+| "List my Artifactory repositories." | Returns repositories via the JFrog CLI. |
+| "Upload this build to Artifactory." | Publishes build artifacts and metadata. |
+| "Run a security audit on this project." | Runs an Xray / Advanced Security audit and summarizes findings. |
+| "Show me details on CVE-2021-23337." | Looks up CVE details in JFrog Advanced Security. |
+| "Create a scoped access token for CI." | Creates an access token with the requested scope. |
+| "Promote this release bundle to production." | Uses Lifecycle / Distribution APIs to promote the bundle. |
 
-- `jfrog` - interact with the JFrog Platform (CLI, MCP, REST/GraphQL).
-- `jfrog-ai-catalog-skills` - discover, install, manage, and publish agent skills from the JFrog AI Catalog via `jf skills` and Agent Guard.
-- `jfrog-package-safety-and-download` - package safety checks and Artifactory-routed downloads.
+### Package safety & download skill
 
-Skills are vendored from [`jfrog/jfrog-skills`](https://github.com/jfrog/jfrog-skills), pinned in `scripts/sync-skills-vendor.json`. Bump the pin and run `npm run sync-skills` to update. See [`VENDOR.md`](VENDOR.md) for the full picture.
+| Ask the agent… | What happens |
+| --- | --- |
+| "Is `lodash@4.17.21` safe to install?" | Checks JFrog Public Catalog signals and curation policy for the package. |
+| "Is this Maven package approved for use?" | Checks curation entitlement and policy for the requested package. |
+| "Download `requests` via JFrog." | Resolves the package through an Artifactory remote cache or curation-aware package manager. |
+
+### MCP server management (Agent Guard)
+
+| Ask the agent… | What happens |
+| --- | --- |
+| "Which MCP servers can I install?" | Returns all MCP servers approved for your current project that you can install. |
+| "What MCP servers do I already have?" | Returns only the MCP servers already installed on your machine. |
+| "Show me the details for the filesystem MCP server." | Returns detailed metadata, required configuration (environment variables, runtime arguments), and active tool policies for a given server. |
+| "Add the GitHub MCP server." | Installs an approved MCP server and syncs its tool policies locally. Secrets are requested via a CLI command — never in chat. |
+| "Update the environment variables for the Slack MCP." | Replaces the configuration for an already-installed server without removing and reinstalling it. |
+| "Remove the Slack MCP server." | Removes the server and its stored credentials from your local setup. Changes apply immediately. |
+| "Log in to the remote Jira MCP server using OAuth." | Authenticates with a remote HTTP-based MCP server (OAuth, API key, or bearer token). |
+
+### How secrets are handled
+
+When an MCP server requires a sensitive configuration value, the agent cannot set
+it directly. Instead, it returns a CLI command for you to copy and run in your
+terminal. Secrets such as API keys, tokens, and connection strings are never
+exposed in the agent chat history.
+
+---
+
+## Troubleshooting
+
+See the [JFrog MCP Registry troubleshooting guide](https://docs.jfrog.com/ai-ml/docs/mcp-registry-troubleshooting).
+
+---
+
+## Updating the vendored skills
+
+The `skills/` tree is vendored from
+[`jfrog/jfrog-skills`](https://github.com/jfrog/jfrog-skills) at the version
+pinned in [`scripts/sync-skills-vendor.json`](scripts/sync-skills-vendor.json).
+To pull a newer upstream release into this repo:
+
+1. Bump `pin` in `scripts/sync-skills-vendor.json` to the new tag (e.g. `v0.23.0`).
+2. Re-sync and commit the refreshed tree:
+
+   ```bash
+   node scripts/sync-skills.mjs
+   ```
+
+   It downloads the pinned tarball from `codeload.github.com` and replaces the
+   directories listed in `paths` (today: `skills/`).
+3. Bump `version` in both [`.codex-plugin/plugin.json`](.codex-plugin/plugin.json)
+   and [`package.json`](package.json) (they must match — CI enforces this) so the
+   published plugin reflects the new skills bundle.
+4. Update the pinned-version link in the [Prerequisites](#prerequisites) section so the
+   skill runtime requirements point at the new tag.
+5. Commit the pin bump, the regenerated `skills/` tree, the version bump, and the
+   README link bump together, and open a PR whose merge commit subject carries a
+   `[patch]` / `[minor]` / `[major]` marker (see [Releasing](#releasing)).
+
+See [`VENDOR.md`](VENDOR.md) for the full picture.
+
+---
+
+## Releasing
+
+Releases are cut automatically by [`.github/workflows/release.yml`](.github/workflows/release.yml)
+when a commit lands on `main` whose **subject line** contains a
+`[major]` / `[minor]` / `[patch]` marker. The workflow reads the version from
+`.codex-plugin/plugin.json` (cross-checked against `package.json`), refuses to
+re-release an existing tag, and publishes a GitHub Release `v<version>` with a
+zipped artifact. A version is released only when both a manifest bump **and** a
+marker commit reach `main`.
+
+---
 
 ## Development
 
 ```
-npm test        # unit tests for the validator
+npm test         # unit tests for the validator
 npm run validate # lint manifests + skill frontmatter
 ```
+
+---
+
+## Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development workflow and
+pull-request expectations.
+
+## Security
+
+See [`SECURITY.md`](SECURITY.md) for how to report vulnerabilities.
+
+## License
+
+Licensed under the [Apache License 2.0](LICENSE).

SECURITY.md

@@ -0,0 +1,15 @@
+# Security
+
+## Reporting a vulnerability
+
+Please report security issues responsibly so we can address them before public disclosure.
+
+- **Email:** [security@jfrog.com](mailto:security@jfrog.com) or follow the process described on [JFrog's security page](https://jfrog.com/trust/report-vulnerability/).
+
+Include steps to reproduce, affected versions or commits, and impact if known.
+
+## Scope
+
+This repository ships an OpenAI Codex plugin (skills and an MCP server manifest).
+
+Do not commit secrets, API keys, or credentials, or any local JFrog runtime data the skills write into a workspace (for example under `.jfrog/`).

VENDOR.md

@@ -7,15 +7,20 @@ The skill packages under `skills/` are vendored from **[jfrog/jfrog-skills](http
 | **Repository** | https://github.com/jfrog/jfrog-skills |
 | **Pinned release** | see `pin` in [`scripts/sync-skills-vendor.json`](scripts/sync-skills-vendor.json) |
 
-Included directories: `jfrog/`, `jfrog-ai-catalog-skills/`, `jfrog-package-safety-and-download/` (as of the pinned release).
+Included skill directories (as of the pinned release): `jfrog/`,
+`jfrog-package-safety-and-download/`, `jfrog-setup-package-managers/`,
+`jfrog-ai-catalog-skills/`, `jfrog-mcp-management/` (JFrog Agent Guard MCP
+management, including the Codex harness), and `jfrog-reference-architecture/`.
 
 ## Refreshing
 
 When the upstream repo publishes a new release, refresh the vendored tree via a PR that:
 
 1. Bumps `pin` in [`scripts/sync-skills-vendor.json`](scripts/sync-skills-vendor.json) to the new tag.
 2. Re-syncs and commits the refreshed `skills/` tree.
-3. Bumps `version` in [`.codex-plugin/plugin.json`](.codex-plugin/plugin.json) so the published plugin version reflects the new skills bundle.
+3. Bumps `version` in **both** [`.codex-plugin/plugin.json`](.codex-plugin/plugin.json) and [`package.json`](package.json) — they must match (CI enforces this) — so the published plugin version reflects the new skills bundle.
+
+Merging the PR does not publish on its own: the merge commit **subject** must carry a `[patch]` / `[minor]` / `[major]` marker, which [`.github/workflows/release.yml`](.github/workflows/release.yml) enforces as the release gate. See the README's [Releasing](README.md#releasing) and [Updating the vendored skills](README.md#updating-the-vendored-skills) sections for the full workflow.
 
 To regenerate the tree locally before opening the PR: