@jfrog/opencode-jfrog-plugin 0.0.2 → 0.0.4

package/skills/jfrog/references/artifactory-entities.md

@@ -0,0 +1,236 @@
+# Artifactory entities
+
+When to read this file:
+
+- Working with **repositories** and you need to understand the difference between local, remote, virtual, and federated types.
+- Managing **artifacts**, **properties**, or **package types**.
+- Working with **builds**, **build promotion**, or **permission targets**.
+- Debugging unexpected behavior related to repo types (e.g. upload failures, missing search results).
+
+For CLI commands see `artifactory-operations.md`. For API gaps see
+`artifactory-api-gaps.md`. For AQL syntax see `artifactory-aql-syntax.md`.
+
+## Repositories
+
+A repository is the primary storage and resolution unit in Artifactory. Every
+repo has a **key** (unique identifier), a **package type** (immutable after
+creation), and a **repository class** (`rclass`) that determines its behavior.
+
+### Repository types
+
+| Type | `rclass` | Behavior | Stores artifacts? |
+|------|----------|----------|-------------------|
+| **Local** | `local` | Hosts artifacts deployed directly (upload, promote, copy, move) | Yes |
+| **Remote** | `remote` | Proxies an external URL; downloads are cached in a companion `-cache` repo | Only in the `-cache` repo |
+| **Virtual** | `virtual` | Aggregates multiple local and remote repos under a single URL for resolution | No (resolves from underlying repos) |
+| **Federated** | `federated` | Local repo that bi-directionally synchronizes across Platform Deployments | Yes (replicated across sites) |
+
+### Key relationships and fields
+
+- `key` — unique repo identifier (e.g. `libs-release-local`)
+- `packageType` — determines layout and protocol (see Package types below)
+- `rclass` — `local`, `remote`, `virtual`, or `federated`
+- `url` — (remote only) the external source URL being proxied
+- `repositories` — (virtual only) ordered list of local/remote repos to aggregate
+- `projectKey` — links repo to a JFrog Project (see `platform-access-entities.md`)
+- `environments` — environments the repo is assigned to (used in RBAC and lifecycle)
+
+### System repositories
+
+Artifactory and Xray maintain several **system repositories** for internal
+platform metadata. These are not user-created and should be excluded when
+iterating over repositories for reporting, scanning, or auditing:
+
+| Pattern | Purpose |
+|---------|---------|
+| `release-bundles` | Release Bundles V1 metadata |
+| `release-bundles-v2` | Release Bundles V2 metadata |
+| `artifactory-build-info` | Default build info storage |
+| `*-release-bundles` | Project-scoped Release Bundles V1 |
+| `*-release-bundles-v2` | Project-scoped Release Bundles V2 |
+| `*-build-info` | Project-scoped build info storage |
+| `*-application-versions` | AppTrust application version metadata |
+
+Including these in aggregate queries (violation counts, storage reports, etc.)
+produces misleading results because they contain platform metadata rather than
+user artifacts.
+
+### Remote repository cache
+
+When Artifactory downloads an artifact through a remote repo, it stores the
+cached copy in a **separate local repo** named `<remote-key>-cache`. This is
+critical for:
+
+- **AQL queries** — search the `-cache` repo, not the remote repo key
+- **Properties** — properties on cached artifacts live on the `-cache` repo
+- **Storage calculations** — cached artifacts consume storage under the `-cache` repo
+
+The remote repo key itself is used for **configuration** (URL, credentials,
+inclusion/exclusion patterns) but does not directly contain artifacts.
+
+### Virtual repository resolution
+
+A virtual repo aggregates **both local and remote repos** under a single URL.
+It resolves artifacts by searching its underlying repos in the configured
+**order** — when the same artifact exists in multiple underlying repos, the
+first match wins.
+
+A virtual repo may designate one of its underlying **local** repos as the
+**default deployment repository**. Uploads through the virtual URL are routed
+to that local repo. Without a default deployment repo, the virtual repo is
+read-only.
+
+```mermaid
+erDiagram
+    VirtualRepo ||--o{ LocalRepo : "aggregates"
+    VirtualRepo ||--o{ RemoteRepo : "aggregates"
+    VirtualRepo ||--o| LocalRepo : "defaultDeploymentRepo"
+    RemoteRepo ||--|| CacheRepo : "has -cache"
+```
+
+## Artifacts
+
+An artifact is a file stored in a repository. Each artifact is uniquely
+identified by the triple **repo + path + name**.
+
+Key attributes:
+- `repo`, `path`, `name` — location identifier
+- `size` — bytes
+- `sha256`, `sha1`, `md5` — checksums (sha256 is the primary identifier for cross-referencing with builds and Xray)
+- `created`, `modified`, `created_by`, `modified_by` — audit fields
+
+Artifacts are **content-addressable** — build info and Xray reference them by
+checksum, not by path. Moving or copying an artifact changes its path but not
+its checksum, so build associations follow the artifact.
+
+## Properties
+
+Key-value metadata pairs attached to artifacts or folders.
+
+- Keys are strings; values are strings or arrays of strings
+- Set via `jf rt set-props`, queried via AQL or the properties API
+- Commonly used for: build metadata, maturity labels, promotion tracking, cleanup policies
+- Properties on remote-cached artifacts live on the `-cache` repo
+
+## Package types
+
+The `packageType` field on a repository determines how Artifactory interprets
+its contents. It controls directory structure conventions, metadata extraction,
+and which client protocols are supported (e.g. Docker registry API, npm
+registry, Maven layout).
+
+Common types: `maven`, `gradle`, `npm`, `docker`, `pypi`, `nuget`, `go`,
+`helm`, `rpm`, `debian`, `generic`.
+
+Package type is **immutable** — it cannot be changed after repo creation. Use
+`generic` when no specific package type applies.
+
+## Build info
+
+A build info record captures CI/CD metadata: which artifacts were produced,
+which dependencies were consumed, and the build environment.
+
+| Field | Description |
+|-------|-------------|
+| `name` + `number` | Unique identifier for a build run |
+| `modules` | List of modules, each with its own artifacts and dependencies |
+| `vcs` | Version control metadata (revision, URL, branch) |
+| `buildAgent`, `agent` | CI tool info |
+| `properties` | Custom build-level properties |
+
+Build info references artifacts **by checksum** (sha256). This means:
+- A build can reference artifacts across multiple repositories
+- Moving an artifact does not break the build association
+- Xray scans build info by resolving checksums to components
+
+Lifecycle: collect → publish → (optionally) promote → (optionally) scan.
+
+## Build promotion
+
+Promotion changes a build's **status** and can copy or move its artifacts
+from a source repo to a target repo.
+
+| Field | Description |
+|-------|-------------|
+| `status` | Target status label (e.g. `staged`, `released`) |
+| `sourceRepo` | Where artifacts currently reside |
+| `targetRepo` | Where artifacts should be moved/copied |
+| `copy` | If `true`, copy instead of move |
+
+Promotion records are queryable via AQL (`build.promotions` domain) and the
+build promotion API.
+
+## Permissions
+
+Permissions define RBAC policies mapping **resources** and **principals**
+(users and groups) to **actions**. Two models exist:
+
+### Permissions V2 (Access Permissions) — current model
+
+Managed by the **Access service** (since Artifactory 7.72.0, recommended from
+7.77.2). Supports all resource types.
+
+| Component | Description |
+|-----------|-------------|
+| `name` | Permission name |
+| `resources` | Map of resource type → targets + actions |
+
+Resource types: `artifact` (repositories), `build`, `release_bundle`,
+`destination` (Edge nodes), `pipeline_source`.
+
+Each resource contains:
+- `targets` — map of target names/patterns to include/exclude patterns
+- `actions.users` — map of username → list of actions
+- `actions.groups` — map of group name → list of actions
+
+Actions use uppercase: `READ`, `ANNOTATE`, `DEPLOY/CACHE`, `DELETE/OVERWRITE`,
+`MANAGE_XRAY_METADATA`, `MANAGE`.
+
+API: `POST/PUT/GET/DELETE /access/api/v2/permissions/{permissionName}`.
+
+Documentation: [Permissions](https://docs.jfrog.com/administration/docs/permissions).
+
+### Permission targets (V1) — legacy model
+
+Managed by **Artifactory**. Still functional and backwards compatible, but
+V2 is recommended for new implementations. The CLI `jf rt permission-target-*`
+commands use this API.
+
+| Component | Description |
+|-----------|-------------|
+| `repositories` | List of repo keys or patterns |
+| `actions.users` | Map of username → list of actions |
+| `actions.groups` | Map of group name → list of actions |
+
+Actions use lowercase: `read`, `write`, `annotate`, `delete`, `manage`.
+
+Does **not** support `destination` or `pipeline_source` resource types.
+
+API: `PUT /artifactory/api/security/permissions/{permissionName}`.
+
+### Key differences
+
+| Aspect | V1 (Permission Targets) | V2 (Access Permissions) |
+|--------|------------------------|------------------------|
+| Managed by | Artifactory | Access service |
+| API base | `/artifactory/api/security/permissions/` | `/access/api/v2/permissions/` |
+| Actions | lowercase (`read`, `write`) | uppercase (`READ`, `WRITE`) |
+| Resource types | repos, builds, release bundles | + destinations, pipeline sources |
+| Pattern fields | `includes_pattern` / `excludes_pattern` | `include_patterns` / `exclude_patterns` |
+| CLI support | `jf rt permission-target-*` | No direct CLI commands (use REST) |
+
+For project-scoped RBAC, see Project roles in `platform-access-entities.md`.
+
+## Replication
+
+Replication synchronizes artifacts and properties between repositories, either
+within the same instance or across Platform Deployments.
+
+| Type | Direction | Trigger |
+|------|-----------|---------|
+| **Push** | Source pushes to target | Scheduled or event-based |
+| **Pull** | Target pulls from source | Scheduled |
+
+Replication configs are JSON templates applied per repository. Both artifact
+content and properties are replicated. For federated repos, replication is
+automatic and bi-directional across all member nodes.

package/skills/jfrog/references/artifactory-operations.md

@@ -0,0 +1,178 @@
+# Artifactory Operations
+
+CLI commands for managing Artifactory resources. All commands use the `jf rt`
+namespace. Run `jf rt --help` to discover subcommands not listed here.
+
+## Repository management
+
+Repositories are created from JSON templates. The workflow is:
+
+1. Get a template: retrieve an existing repo config via
+   `jf api /artifactory/api/repositories/<repo-key>`
+   and modify it, or craft JSON manually.
+   Note: `jf rt repo-template` is interactive and cannot be used by agents.
+2. Create: `jf rt repo-create <template.json>`
+3. Update: `jf rt repo-update <template.json>`
+4. Delete: `jf rt repo-delete <repo-pattern> --quiet`
+
+To list repositories, use:
+`jf api /artifactory/api/repositories`
+
+## File operations
+
+- Upload: `jf rt upload <source> <target>`
+- Download: `jf rt download <source> [target]`
+- Search: `jf rt search <pattern>`
+- Move: `jf rt move <source> <target>`
+- Copy: `jf rt copy <source> <target>`
+- Delete: `jf rt delete <pattern>`
+- Set properties: `jf rt set-props <pattern> "key=value"`
+- Delete properties: `jf rt delete-props <pattern> "key"`
+
+### Searching across repositories
+
+`jf rt search` expects a `<repo>/<pattern>` argument. When the repo is unknown,
+agents tend to use a leading wildcard (`jf rt search "*/path/..."`), which
+generates an unscoped AQL internally and can time out on large instances.
+
+Use a direct AQL query with `name` and `path` criteria instead — omitting the
+`repo` field searches all accessible repos via indexed columns:
+
+```bash
+jf api /artifactory/api/search/aql \
+  -X POST -H "Content-Type: text/plain" \
+  -d 'items.find({
+    "name":"<artifact-filename>",
+    "path":"<directory/path/within/repo>"
+  }).include("repo","path","name","size","sha256")'
+```
+
+Add `"repo":"<repo-name>"` to the criteria when the target repo is known, to
+narrow the search further.
+
+## Build info
+
+**Project scoping rule:** Append `?project=<key>` to **every** build detail
+API call. When the user provides a project key, use it. When no project key
+is provided, use `?project=default` (the built-in default project that covers
+the `artifactory-build-info` repo). For AQL queries, scope by
+`"repo":"<project-key>-build-info"` (or `"repo":"artifactory-build-info"` for
+the default project).
+
+**Server rule:** A 404 from a `?project=<key>` build call is **not** a signal
+to try a different server. Use only the resolved server; on any failure,
+report and stop. See `SKILL.md` § *Server selection rules*.
+
+### Publishing builds
+
+- Collect env: `jf rt build-collect-env <name> <number>`
+- Add git info: `jf rt build-add-git <name> <number>`
+- Publish: `jf rt build-publish <name> <number>`
+- Promote: `jf rt build-promote <name> <number> <target-repo>`
+- Discard: `jf rt build-discard <name>`
+
+### Listing build names
+
+**Do not use `GET /api/build`** — it has no pagination and times out on large
+instances. Always use AQL with `limit` and `offset`.
+
+**All builds** (no project scope):
+
+```bash
+jf api /artifactory/api/search/aql \
+  -X POST -H "Content-Type: text/plain" \
+  -d 'builds.find().include("name","number","repo","created").sort({"$desc":["created"]}).offset(0).limit(100)'
+```
+
+**Project-scoped** — filter by the project's build-info repository
+(`<project-key>-build-info`, or `artifactory-build-info` for the default
+project):
+
+```bash
+jf api /artifactory/api/search/aql \
+  -X POST -H "Content-Type: text/plain" \
+  -d 'builds.find({"repo":"<project-key>-build-info"}).include("name","number","repo","created").sort({"$desc":["created"]}).offset(0).limit(100)'
+```
+
+**Pagination:** The response includes a `range` object with `total` (total
+matching records). If `total` exceeds the `limit`, tell the user: *"Showing
+first 100 of N results (paginated). Ask for the next batch if needed."*
+For subsequent pages, increment `offset` by 100.
+
+**Output rule (mandatory):** AQL returns one row per name+number pair.
+Extract **unique build names** client-side (e.g.
+`jq '[.[].builds.name] | unique'`). Present **only the deduplicated list of
+build names** to the user. **Do not** include build numbers, timestamps, run
+counts, or any per-run details in the response — not even as a "bonus" or
+"most recent" table. The user is asking "what builds exist", not "what runs
+happened". Only show run-level details if the user explicitly asks for them
+in a follow-up.
+
+### Listing runs of a specific build
+
+```bash
+jf api /artifactory/api/search/aql \
+  -X POST -H "Content-Type: text/plain" \
+  -d 'builds.find({"name":"<build-name>"}).include("name","number","repo","created").sort({"$desc":["created"]}).offset(0).limit(100)'
+```
+
+Add `"repo":"<project-key>-build-info"` to the criteria when a project key
+is known. Apply the same pagination rules as above.
+
+### Retrieving full build info
+
+Use the REST detail endpoint for a **single** build run. Always include
+`?project=<key>` (or `?project=default` when no key is provided):
+
+```bash
+jf api "/artifactory/api/build/<name>/<number>?project=<key>"
+```
+
+This is the only `/api/build` endpoint that should be used — it returns a
+single record and does not need pagination.
+
+### When a build is not found
+
+If the detail call returns 404, the build likely belongs to a different
+project. **Ask the user for the project key** rather than searching across
+repos or servers.
+
+### Repository listing vs build-info
+
+`GET /artifactory/api/repositories?project=<key>&type=buildinfo` may return
+an empty list even when project-scoped build info exists (for example under
+a `*-build-info` repository). Prefer AQL to
+discover builds; do not treat an empty repository
+list as proof that no
+builds exist.
+
+## Permissions
+
+Permission targets use JSON templates.
+Note: `jf rt permission-target-template` is interactive.
+
+- Create: `jf rt permission-target-create <template.json>`
+- Update: `jf rt permission-target-update <template.json>`
+- Delete: `jf rt permission-target-delete <name>`
+
+## Users and groups
+
+- Create users: `jf rt users-create --csv <file>`
+- Create single user: `jf rt user-create` (check `--help` for options)
+- Delete users: `jf rt users-delete <pattern>`
+- Create group: `jf rt group-create <name>`
+- Delete group: `jf rt group-delete <name>`
+- Add users to group: `jf rt group-add-users <group> <users-list>`
+
+To get user details or update users, use `jf api`:
+```
+jf api /access/api/v2/users/<username>
+```
+
+## Replication
+
+Replication configs use JSON templates.
+Note: `jf rt replication-template` is interactive.
+
+- Create: `jf rt replication-create <template.json>`
+- Delete: `jf rt replication-delete <repo-key>`

package/skills/jfrog/references/catalog-entities.md

@@ -0,0 +1,219 @@
+# Catalog entities
+
+When to read this file:
+
+- Querying **public package metadata** (descriptions, vulnerabilities, licenses, operational info).
+- Working with the **Custom Catalog** (org-specific labels, package views, federation).
+- Looking up **vulnerability details** beyond what Xray provides (advisories, EPSS, CWE, known exploits).
+- Querying **OpenSSF scorecards**, **ML model metadata**, or **MCP service** registries.
+- Using the OneModel GraphQL API with `publicPackages`, `customPackages`,
+  `publicSecurityInfo`, `publicLegalInfo`, `publicOperationalInfo`,
+  `publicCatalogLabels`, or `publicRemoteServices` query roots.
+
+Catalog entities are accessed via the **OneModel GraphQL API**
+(`/onemodel/api/v1/graphql`).
+
+For the OneModel query workflow (credentials, schema fetch, validation,
+execution), read `references/onemodel-graphql.md`.
+
+## Two catalog layers
+
+| Layer | Scope | Description |
+|-------|-------|-------------|
+| **Public Catalog** | Global | JFrog's curated package database — security, legal, and operational metadata for public packages across ecosystems |
+| **Custom Catalog** | Organization | Org-specific overlay — custom labels, per-org package views, federation config |
+
+The Custom Catalog builds on top of the Public Catalog. A public package
+can be enriched with org-specific labels and metadata through the Custom
+Catalog without altering the underlying public data.
+
+## Public Catalog entities
+
+### PublicPackage
+
+A package as known to JFrog's global package database.
+
+| Field | Description |
+|-------|-------------|
+| `name` | Package name (e.g. `lodash`, `spring-boot-starter-web`) |
+| `type` | Package type (e.g. `npm`, `maven`, `pypi`) |
+| `ecosystem` | Ecosystem identifier |
+| `description` | Rich-text description |
+| `homepage`, `vcsUrl` | Package URLs |
+| `vendor` | Maintainer or organization |
+| `latestVersion` | Most recent version |
+| `trendingScore` | Popularity score |
+| `publishedAt`, `modifiedAt` | Timestamps |
+| `mlModel` | ML model metadata (for HuggingFace etc.) |
+
+Connections: `versionsConnection`, `publicLabelsConnection`, `legalInfo`,
+`operationalInfo`, `securityInfo`.
+
+Query: `publicPackages.searchPackages(where: {...})`.
+
+### PublicPackageVersion
+
+A specific version with security, legal, and operational analysis.
+
+| Field | Description |
+|-------|-------------|
+| `version` | Version string |
+| `isLatest` | Whether this is the latest version |
+| `isListedVersion` | Whether visible in Catalog UI |
+| `publishedAt`, `modifiedAt` | Timestamps |
+| `trendingScore` | Version-level popularity |
+| `dependencies` | Dependency information |
+| `mlModelMetadata`, `mlInfo` | ML/AI-related metadata |
+
+Each version carries three info blocks:
+- `securityInfo` — vulnerability data, maliciousness, contextual analysis
+- `legalInfo` — licenses, copyrights
+- `operationalInfo` — end-of-life, OpenSSF scores, popularity metrics
+
+### PublicVulnerability
+
+Vulnerability data richer than what Xray violations expose. Useful for
+deep-dive security analysis and advisory lookups.
+
+| Field | Description |
+|-------|-------------|
+| `name` | CVE identifier (e.g. `CVE-2021-44228`) |
+| `ecosystem` | Affected ecosystem |
+| `severity` | `CRITICAL`, `HIGH`, `MEDIUM`, `LOW` |
+| `description` | Detailed impact description |
+| `cvss` | CVSS scores — v2, v3, **and v4** |
+| `epss` | EPSS (Exploit Prediction Scoring System) — exploit likelihood |
+| `knownExploit` | Known exploit information |
+| `withdrawn` | Whether the CVE has been retracted |
+| `aliases` | Alternative identifiers |
+| `references` | Advisory URLs |
+| `publishedAt`, `modifiedAt` | Timestamps |
+
+Advisory sources (via `advisories` connection):
+- **NVD** — NIST National Vulnerability Database
+- **GHSA** — GitHub Security Advisory
+- **JFrog Advisory** — JFrog's own research (includes impact reasons)
+- **Debian Security Tracker**
+- **RedHat OVAL**
+
+Additional connections: `cwesConnection` (CWE entries), `cpesConnection`
+(CPE entries), `publicPackageInfo` (affected packages and versions).
+
+Query: `publicSecurityInfo.searchVulnerabilities(where: {...})`.
+
+#### Filtering limitations
+
+`searchVulnerabilities` can filter by CVE name, ecosystem, severity, CVSS,
+EPSS, known exploit status, and publication date — but **not** by affected
+package name. There is no `hasPublicPackageInfoWith` or similar filter on
+`PublicVulnerabilityWhereInput`. To find vulnerabilities affecting a specific
+package, use one of these alternatives:
+
+- **Version-level security info** (GraphQL): query
+  `publicPackages.getPackage(type, name)` and navigate to
+  `versionsConnection → securityInfo → vulnerabilitiesConnection` to get
+  CVEs affecting specific versions.
+- **Individual CVE lookup**: use `searchVulnerabilities(where: { name: "<CVE>" })`
+  and inspect `publicPackageInfo.vulnerablePublicPackagesConnection` on the
+  `generic` ecosystem entry.
+
+#### Ecosystem multiplicity
+
+A single CVE appears as multiple `PublicVulnerability` entries — one per
+ecosystem. The `ecosystem` field determines which entry you see:
+
+| Ecosystem | Contains |
+|-----------|----------|
+| `generic` | Non-OS package-level data (npm, maven, pypi, go, etc.) — includes `publicPackageInfo` with vulnerable versions and fix versions |
+| `debian`, `redhat`, `ubuntu`, etc. | OS-specific advisory data — severity may differ from NVD; `publicPackageInfo` is typically empty (OS packages are tracked separately) |
+
+When looking up a CVE by name, `searchVulnerabilities(where: { name: "<CVE>" })`
+returns all ecosystem entries. To get affected packages and fix versions for
+libraries like npm or maven, filter for or focus on the `generic` ecosystem
+entry. `getVulnerability` requires both `name` and `ecosystem` — use
+`searchVulnerabilities` when the ecosystem is unknown.
+
+### PublicLicense
+
+License metadata with permission, condition, and limitation details.
+
+| Field | Description |
+|-------|-------------|
+| `name` | License name (e.g. `Apache-2.0`, `MIT`) |
+| `spdxId` | SPDX identifier |
+| `permissions` | What the license permits |
+| `limitations` | Restrictions imposed |
+| `patentConditions` | Patent grant conditions |
+| `noticeFiles` | Required notices |
+
+Query: `publicLegalInfo.searchLicenses(where: {...})`.
+
+### PublicPackageOperationalInfo
+
+Operational risk assessment for packages and versions.
+
+| Entity | Key data |
+|--------|----------|
+| **OpenSSF scorecard** | Overall score, individual checks with scores and pass/fail |
+| **End-of-life** | Whether the package or version is EOL, justification |
+| **Popularity** | JFrog popularity by segment and subscription tier, download counts |
+
+### MCP services and tools
+
+The Public Catalog also indexes MCP (Model Context Protocol) services:
+
+| Entity | Description |
+|--------|-------------|
+| `PublicMcpService` | An MCP service with name, description, version |
+| `PublicMcpTool` | A tool exposed by an MCP service with arguments |
+| `PublicMcpRemote` | Remote MCP server configuration |
+
+Query: `publicRemoteServices.searchMcpServices(where: {...})`.
+
+## Custom Catalog entities
+
+### CustomPackage
+
+A package in the organization's private catalog view.
+
+| Field | Description |
+|-------|-------------|
+| `customCatalogId` | Org-scoped identifier |
+| `name`, `type`, `ecosystem`, `namespace` | Package identity |
+| `isListedPackage` | Whether visible in Catalog UI |
+| `customCatalogAddedAt`, `customCatalogModifiedAt` | Org-specific timestamps |
+
+Connections: `versionsConnection`, `legalInfo`,
+`customCatalogLabelsConnection`.
+
+### CustomCatalogLabel
+
+Organization-defined labels for categorizing packages.
+
+| Field | Description |
+|-------|-------------|
+| `name` | Label name |
+| `description` | What the label represents |
+| `color` | Display color |
+| `labelType` | `MANUAL` or `AUTOMATIC` |
+| `assignmentInfo` | How and when the label was assigned |
+
+Labels can be assigned to both custom packages and public packages/versions
+within the org's catalog scope. The Custom Catalog mutations allow
+creating, updating, and deleting labels.
+
+### CustomCatalogFederation
+
+Configuration for federating catalog data across JFrog deployments.
+
+## Catalog vs. Xray vs. Stored Packages
+
+These three domains provide different views of package and security data:
+
+| Aspect | Catalog | Xray | Stored Packages |
+|--------|---------|------|-----------------|
+| **Scope** | Global knowledge base + org overlay | Instance-scoped scanning | Instance-scoped storage |
+| **Security** | CVE advisories, EPSS, CVSS v2/v3/v4, known exploits | Watches, policies, violations | Vulnerability summary (deprecated) |
+| **Packages** | Public metadata (description, homepage, OpenSSF) | Components identified during scanning | Packages/versions stored in Artifactory |
+| **Access** | GraphQL only | REST + CLI (`jf api /xray/...`) | GraphQL only |
+| **Use case** | Research, compliance reporting, package evaluation | Runtime enforcement, CI/CD gating | Inventory, location queries |