@jfrog/opencode-jfrog-plugin 0.0.2 → 0.0.4

package/skills/jfrog/references/general-bulk-operations-and-agent-patterns.md

@@ -0,0 +1,93 @@
+# Bulk operations and agent execution patterns
+
+Platform-wide guidance for agents that gather data from multiple JFrog products
+(Artifactory, Xray, Access, Distribution, etc.), run long shell
+sequences, or parallelize work. Product-specific field names and endpoints live
+in the other `references/*` files; this document describes **patterns**, not
+one workflow.
+
+## List vs detail responses
+
+Many REST surfaces expose a **light list** (keys, names, minimal fields) and a
+**richer GET by id or key**. Fields needed for audits, reporting, joins, or
+permission checks may appear **only** on the detail response. Before building a
+multi-step flow on a single list call, confirm in API docs or with a sample GET
+whether the fields you need are present.
+
+## Volume, batching, and timeouts
+
+- Estimate **N** round-trips (list + per-item GETs, paginated APIs, etc.) before
+  starting so execution time and tool timeouts stay predictable.
+- Prefer batching independent reads in one Shell invocation when credentials and
+  tier match (see SKILL.md **Batch and parallel execution**).
+- Split very large work across chunks, parallel Shell calls, or subagents when
+  the skill's tiering guidance says so.
+- Before starting an N+1 loop (list + per-item detail), **estimate wall time**
+  as roughly `N * 1.5s` for sequential calls. Set `block_until_ms` to at
+  least that estimate plus a 30-second buffer.
+- For loops exceeding ~60 items, prefer a single Shell invocation that writes
+  progress to a log file (`>> /tmp/jf-progress-$$.log`) so partial results
+  are visible even if the job is interrupted.
+- If the task is read-only and items are independent, consider Tier 2 or
+  Tier 3 parallelism (see `general-parallel-execution.md`) to reduce total time —
+  but respect rate limits and keep concurrency modest (4-8 parallel calls).
+
+## Parallelism and shared files
+
+**Unsafe:** Multiple concurrent processes appending lines to the **same** file
+(JSONL, logs, ndjson) without synchronization. Output can interleave on one
+line and break parsers (e.g. JSON "Extra data" errors).
+
+**Safer:**
+
+- Write sequentially to one file; or
+- One temp file per worker or chunk, then concatenate; or
+- Use advisory locking (`flock`) if one file must be shared.
+
+For bulk API or CLI output files, use `/tmp` or `mktemp`; do not use
+`~/.jfrog/skills-cache/` except for `jfrog-skill-state.json` and the OneModel
+schema file (see main SKILL.md).
+
+## Shell hygiene
+
+- Use `set -euo pipefail` in non-trivial scripts so failures are not silent.
+- Use unique temp paths (e.g. `$$` in the filename) and **echo the expanded
+  path** so it can be reused across Shell calls (see SKILL.md **Preserving
+  command output** for the `$$` + echo, session ID, and hardcoded patterns).
+- Parse CLI and API JSON with **`jq`**.
+
+## Safe multi-response collection
+
+When looping over items (repos, builds, users) and fetching detail for each:
+
+1. Save each response to a variable or per-item file.
+2. Validate with `jq -e . >/dev/null 2>&1` before appending.
+3. On validation failure, write a structured error line so the caller can
+   report partial results instead of crashing.
+4. After the loop, `jq -s '.' results.ndjson` to produce a single array.
+
+```bash
+: >results.ndjson
+while read -r key; do
+  body=$(jf api "/artifactory/api/repositories/$key" || true)
+  if echo "$body" | jq -e . >/dev/null 2>&1; then
+    echo "$body" | jq -c . >>results.ndjson
+  else
+    printf '{"key":"%s","_error":"invalid_response"}\n' "$key" >>results.ndjson
+  fi
+done < <(jq -r '.[].key' list.json)
+jq -s '.' results.ndjson > details.json
+```
+
+Never pipe a loop of `jf api` calls directly into `jq -s` without
+per-body validation.
+
+## Where to find product specifics
+
+- Artifactory REST nuances: `references/artifactory-api-gaps.md`
+- Platform admin / Access: `references/platform-admin-api-gaps.md`
+- JFrog Projects (endpoints): `references/projects-api.md`
+- Joining Artifactory repos to Projects (`projectKey`, roles, environments):
+  `references/platform-access-entities.md`
+- Platform API invocation (all products through `jf api`): see
+  `SKILL.md` § *Invoking platform APIs with `jf api`*

package/skills/jfrog/references/general-parallel-execution.md

@@ -0,0 +1,131 @@
+# Batch and Parallel Execution
+
+When a task requires multiple independent operations, use the lightest
+parallelism mechanism that fits. Three tiers are available, from lightest to
+heaviest:
+
+| Tier | Mechanism | Best for |
+|------|-----------|----------|
+| 1 | Single Shell call with `&&` | Few commands, same credentials |
+| 2 | Parallel Shell tool calls | Independent commands that can run concurrently |
+| 3 | Parallel subagents (Task tool) | Large multi-step jobs where each branch needs its own reasoning |
+
+## Tier 1: Batch within a single Shell call
+
+Combine independent commands with `&&`. All JFrog API calls go through the
+same `jf api` command and the same `jf config` server, so batching them
+together is both safe and efficient:
+
+```bash
+jf api /artifactory/api/repositories > /tmp/jf-repos-$$.json && \
+jf api /artifactory/api/system/ping    > /tmp/jf-ping-$$.json && \
+jf api /artifactory/api/storageinfo    > /tmp/jf-storage-$$.json
+```
+
+Cross-product reads batch the same way:
+
+```bash
+jf api /access/api/v2/users/        > /tmp/jf-users-$$.json && \
+jf api /access/api/v2/groups/       > /tmp/jf-groups-$$.json && \
+jf api /access/api/v2/permissions/  > /tmp/jf-perms-$$.json
+```
+
+## Tier 2: Parallel Shell tool calls
+
+Use multiple Shell tool calls in the same message when the commands are
+independent and the total runtime benefits from concurrency:
+
+```bash
+# Shell call 1 — echo the expanded path so the agent can reference it later
+OUT=/tmp/jf-repos-$$.json
+jf api /artifactory/api/repositories > "$OUT" && echo "$OUT"
+
+# Shell call 2 (parallel) — same pattern, different PID
+OUT=/tmp/jf-users-$$.json
+jf api /access/api/v2/users/ > "$OUT" && echo "$OUT"
+```
+
+Each parallel Shell call gets a different PID, so `$$` expands to different
+values. Echo the path so the agent knows the literal filename for cross-call
+use (see SKILL.md **Preserving command output**).
+
+## Tier 3: Parallel subagents
+
+For tasks with multiple independent branches that each require several steps
+or their own reasoning — such as generating a platform health report with
+separate sections, auditing both repository config and security policies, or
+comparing configurations across servers the user explicitly named — launch
+parallel subagents using the Task tool.
+
+Each subagent runs autonomously, executes its own CLI/API calls, and returns
+a structured result. The parent agent assembles the final answer.
+
+### Example — platform audit with three parallel subagents
+
+```
+Subagent 1 (shell): "Collect repository data"
+  → jf api /artifactory/api/repositories
+  → jf api /artifactory/api/storageinfo
+  → Return repo count, types, total size
+
+Subagent 2 (shell): "Collect security configuration"
+  → jf api /xray/api/v2/policies
+  → jf api /xray/api/v2/watches
+  → Return policy count, watch count, coverage gaps
+
+Subagent 3 (shell): "Collect user and permission data"
+  → jf api /access/api/v2/users/
+  → jf api /access/api/v2/groups/
+  → jf api /access/api/v2/permissions/
+  → Return user count, group count, admin users
+```
+
+All three subagents run concurrently. Once all complete, the parent agent
+merges their results into a unified report.
+
+### How to structure a subagent prompt
+
+1. State the goal clearly (e.g. "Collect all Xray policies and watches").
+2. Provide the exact commands to run, or name the API tier and let the
+   subagent discover via `--help`.
+3. Tell the subagent to save output to `/tmp/jf-<label>-$$.json`, echo the
+   expanded path, and return a structured summary.
+4. Specify what to return (counts, lists, specific fields) so the parent can
+   assemble the final output without re-reading raw data.
+
+### Subagent type selection
+
+- Use `subagent_type="shell"` for straightforward command sequences where the
+  commands are known ahead of time.
+- Use `subagent_type="generalPurpose"` when the subagent needs to read skill
+  references, discover commands via `--help`, or adapt its approach based on
+  intermediate results.
+
+## When to use each tier
+
+| Scenario | Tier |
+|----------|------|
+| 2–5 independent reads, same server | 1 (single Shell) |
+| Many independent reads where concurrency cuts total runtime | 2 (parallel Shell) |
+| Full platform audit, multi-section report, cross-server comparison | 3 (subagents) |
+| Task branches need different reference files or reasoning | 3 (subagents) |
+| Simple one-shot data fetch | 1 (single Shell) |
+
+## When NOT to parallelize
+
+- A later command depends on the output of an earlier one (use sequential
+  calls instead and process the output in between).
+- The calls include **mutating operations** — keep those separate so the user
+  can review each one.
+- Commands would target different servers — only operate on the server(s) the
+  user explicitly named (or the default). Never fall back to or iterate
+  through other configured servers. See SKILL.md **Server selection rules**.
+- The task is small enough that a single Shell call completes in seconds — the
+  overhead of launching subagents is not justified.
+
+## Aggregating many outputs (JSONL, logs, ndjson)
+
+Do **not** have multiple background processes append **unsynchronized** to the
+same file — lines can interleave and corrupt machine-readable output. Prefer
+sequential writes, one file per worker or chunk then concatenate, or file
+locking. See `references/general-bulk-operations-and-agent-patterns.md`.

package/skills/jfrog/references/general-use-case-hints.md

@@ -0,0 +1,27 @@
+# Use-case hints (living log)
+
+Symptoms, causes, and mitigations discovered while using this skill on real
+tasks. **Append** a new row when you confirm a novel issue (any product or
+workflow). Keep entries short and actionable.
+
+| Area | Symptom | Cause | Mitigation | Notes |
+|------|---------|-------|------------|-------|
+| Parallel I/O | JSONL or ndjson parse errors ("Extra data", merged objects on one line) | Concurrent unsynchronized `>>` to the same file from parallel jobs | Sequential writes, one file per worker then `cat`, or `flock` | Generic pattern for any bulk CLI output |
+| APIs (general) | Report or script missing fields that appear in the UI or docs | List endpoint omitted fields; detail GET has the full record | List then GET by id/key when needed; see `general-bulk-operations-and-agent-patterns.md` | Applies across products |
+| Access / Projects | Project groups list looks empty in code | Response may use `members` for the group entries, not `groups` | Accept both keys when parsing | See `projects-api.md` |
+| Bulk detail fetches | `jq` parse error ("Extra data" or "Invalid ...") on slurped detail array | One or more detail GETs returned empty/HTML/error body; `jq -s` chokes on non-JSON mixed in | Validate each response with `jq -e .` before appending; write error placeholder for failures; see `general-bulk-operations-and-agent-patterns.md` | Applies to any per-item loop (repos, builds, users) |
+| Agent timeouts | Shell job silently moves to background; no captured output | `block_until_ms` too low for N sequential API calls (~1-2s each) | Estimate `N * 1.5s + 30s` buffer; set `block_until_ms` accordingly; or use parallel execution | Default 30s insufficient for >20 items |
+| Sandbox + workspace writes | Generated report JSON or HTML not written; script exits 0 but file missing | Sandbox blocks some paths; agents sometimes wrongly target `~/.jfrog/skills-cache/` for scratch files (disallowed — only state + schema belong there) | Write reports and API responses under `/tmp` or the user workspace; only the two allowed cache files (`jfrog-skill-state.json`, `onemodel-schema-<id>.graphql`) belong in `~/.jfrog/skills-cache/` | `skills-cache/` is not a temp directory; see SKILL.md **`~/.jfrog/skills-cache/` — allowed files only** |
+| `jf api` and redirects | Responses are empty or contain redirect HTML instead of expected content | `jf api` does not expose `-L`; it follows the redirect chain the Artifactory REST API returns by default but will not transparently hop across an unexpected 3xx to a binary URL | For remote-repo artifact content (e.g. fetching a file via `/artifactory/<repo>/<path>`), use `jf rt dl` instead of `jf api` — it handles 302s to CDN hosts. Reserve `jf api` for REST metadata/operation endpoints. | Applies when reading artifact **content**, not REST metadata |
+| Curation testing | `jf curation-audit` or `jf npm install` through a curated remote shows 1 download for the tested package even though no user downloaded it | The curation test itself fetches the package through Artifactory, which creates a cache entry and increments download stats | Account for this in download history analysis — the download was the curation test, not a real consumer pull | Also applies to `jf npmc` + `jf npm install` flows |
+| Agent-invented mutations | Agent copies or moves artifacts into a local repo to satisfy a precondition for a different operation (e.g., copy a package so evidence can be created on it) | Requested operation failed because the artifact was not in the specified repo; agent autonomously performed a copy/move/upload to "fix" the gap | **Never** perform unrequested copy, move, upload, or create-repo to work around a failed precondition — stop and report the gap to the user. See SKILL.md § Cautious execution rule 6 | Copying into a local repo can silently change virtual repo resolution for all consumers, trigger replication, and affect Xray indexing |
+
+## How to extend this file
+
+1. Reproduce the issue once on a real server or fixture.
+2. Add one table row (or a short new subsection if the table is a poor fit).
+3. Prefer general wording so the next use case on a different product still benefits.
+4. Before appending, scan existing entries for duplicates or near-duplicates —
+   update the existing row instead of adding a new one.
+5. Keep this file under 80 rows. If it grows beyond that, consolidate related
+   entries or promote recurring patterns into the relevant reference file.

package/skills/jfrog/references/jfrog-brand-html-report.md

@@ -0,0 +1,98 @@
+# JFrog-aligned styling for standalone HTML reports
+
+Use this reference when producing a **pretty, self-contained HTML file** (single file with embedded CSS) that presents data fetched from the JFrog Platform. It complements the operational steps in `SKILL.md`; it does not replace [JFrog Brand Guidelines](https://jfrog.com/brand-guidelines/).
+
+## When this applies
+
+- The user asked for HTML output (not only Markdown).
+- The report should feel **professionally aligned** with JFrog’s public brand (terminology, palette, restraint) without impersonating JFrog or implying endorsement.
+
+## Authoritative source
+
+- **Brand guidelines**: [https://jfrog.com/brand-guidelines/](https://jfrog.com/brand-guidelines/) — rules for JFrog Marks, nominative use, naming, and what not to do (e.g. do not copy JFrog’s site “look and feel” wholesale, do not modify official logos, do not use the favicon on your pages).
+- **Media Kit**: linked from that page (logos in AI/PNG). Use official assets only if the user needs a logo; scale proportionally and add clarifying context per the guidelines.
+
+## Naming and copy
+
+- Use **JFrog** with a capital **JF** in prose. For the CLI command name, use lowercase **`jfrog`** where that matches actual command-line usage (per JFrog’s own spelling note on the brand page).
+- Use **correct product names**: JFrog Artifactory, JFrog Xray, JFrog Platform, etc., when referring to those products.
+- Give the report a **distinct title** that describes the content (e.g. “Repository inventory — Acme Corp — 2026-03-24”). Do **not** name the file or the document as if it were an official JFrog publication.
+- Add a short **footer or subtitle** when helpful, e.g. that the document was generated from the user’s environment for their analysis, and is **not** sponsored or endorsed by JFrog (nominative use only).
+
+## Visual design (aligned, not a clone)
+
+The brand page asks users not to imitate JFrog’s proprietary layout and marks. For HTML reports:
+
+- Prefer a **clean, neutral layout**: plenty of whitespace, readable line length, clear hierarchy (one `<h1>`, logical `<h2>`/`h3>`).
+- Use **one accent color** associated with JFrog’s digital brand (green) for links, key metrics, or section rules — not for large solid backgrounds that mimic marketing hero sections.
+- Use **system or widely available fonts** (`system-ui`, sensible fallbacks) unless the user asks for a specific font. Do not claim typography is “the official JFrog font” unless taken from approved assets.
+- Avoid decorative elements that could be confused with JFrog logos, patterns, or the jfrog.com chrome.
+
+## Suggested CSS tokens (embedded in `<style>`)
+
+These are **practical defaults** for internal or technical reports. Adjust if the user’s org has its own template; verify accent against current brand materials if the output is customer-facing.
+
+```css
+:root {
+  /* Accent — common on JFrog digital properties; confirm vs Media Kit / brand updates */
+  --jfrog-accent: #40be46;
+  --jfrog-accent-hover: #36a63d;
+  /* Neutrals */
+  --text-primary: #1a1a1a;
+  --text-muted: #5c5c5c;
+  --border-subtle: #e4e4e4;
+  --bg-page: #ffffff;
+  --bg-muted: #f7f8f8;
+}
+
+body {
+  font-family: system-ui, -apple-system, "Segoe UI", Roboto, Ubuntu, sans-serif;
+  color: var(--text-primary);
+  background: var(--bg-page);
+  line-height: 1.5;
+  margin: 0;
+  padding: 2rem clamp(1rem, 4vw, 3rem);
+  max-width: 56rem;
+}
+
+a {
+  color: var(--jfrog-accent);
+}
+a:hover {
+  color: var(--jfrog-accent-hover);
+}
+
+h1 {
+  font-weight: 700;
+  font-size: 1.75rem;
+  border-bottom: 3px solid var(--jfrog-accent);
+  padding-bottom: 0.35rem;
+}
+
+table {
+  border-collapse: collapse;
+  width: 100%;
+  font-size: 0.95rem;
+}
+th, td {
+  border: 1px solid var(--border-subtle);
+  padding: 0.5rem 0.65rem;
+  text-align: left;
+}
+thead {
+  background: var(--bg-muted);
+}
+
+code, pre {
+  font-family: ui-monospace, "Cascadia Code", "SF Mono", Menlo, monospace;
+  font-size: 0.9em;
+}
+```
+
+## Optional logo
+
+Only if the user explicitly wants a logo: use files from the **JFrog Media Kit**, do not alter colors or geometry, and include nearby text that this report is **about** their JFrog deployment, not **by** JFrog — consistent with nominative-use expectations on the brand page.
+
+## Markdown alternative
+
+If the user prefers **Markdown** only, follow normal project conventions; apply this file when the deliverable is **standalone HTML** with branding-aligned styling.

package/skills/jfrog/references/jfrog-cli-install-upgrade.md

@@ -0,0 +1,30 @@
+# JFrog CLI Install & Upgrade
+
+## Installing the JFrog CLI
+
+If `jf` is not installed (environment check exits with code 2), guide the user:
+
+```bash
+# macOS
+brew install jfrog-cli
+
+# Linux / generic
+curl -fL https://install-cli.jfrog.io | sh
+```
+
+After installation, run `jf --version` to confirm and refresh the cache.
+
+## Upgrading the JFrog CLI
+
+If the environment check reports a newer version is available, inform the user
+and offer to upgrade:
+
+```bash
+# macOS
+brew upgrade jfrog-cli
+
+# Linux / generic (reinstall)
+curl -fL https://install-cli.jfrog.io | sh
+```
+
+After upgrading, run `jf --version` to confirm and refresh the cache.

package/skills/jfrog/references/jfrog-entity-index.md

@@ -0,0 +1,112 @@
+# JFrog entity index
+
+When to read this file:
+
+- The user mentions a JFrog entity and you need to identify which **domain** it belongs to.
+- You are planning an operation that spans **multiple products** (e.g. build → scan → release).
+- You need a quick **one-line definition** before deciding whether to load the full domain reference.
+- You need **GraphQL (OneModel)** entry points (workflow, examples, patterns) —
+  see [GraphQL (OneModel)](#graphql-onemodel) below.
+
+After identifying the domain, follow the pointer in the **Reference** column for
+detailed definitions, relationships, and agent rules.
+
+## Cross-product flow
+
+```mermaid
+flowchart TD
+    Art[Artifact] -->|stored in| Repo[Repository]
+    Repo -->|abstracted as| SP[Stored Package]
+    Build[Build Info] -->|references by checksum| Art
+    Repo -->|indexed by| Xray
+    Build -->|scanned by| Xray
+    Xray -->|evaluates via watches/policies| Viol[Violation]
+    Build -->|assembled into| RB[Release Bundle]
+    Art -->|included in| RB
+    RB -->|promoted through| Env[Environments]
+    RB -->|distributed to| Edge[Edge Nodes]
+    RB -->|sources| App[Application Version]
+    Build -->|sources| App
+    SP -->|package location| App
+    App -->|promoted through stages| AppStage[App Stages]
+    Evd[Evidence] -.->|attests| RB
+    Evd -.->|attests| App
+    Evd -.->|attests| SP
+    Cat[Catalog] -.->|enriches metadata| SP
+```
+
+Key takeaway: **artifacts** are the atomic unit. Builds reference them,
+Xray scans them, release bundles collect them, distribution delivers them.
+**Applications** orchestrate the top-level release flow. **Stored Packages**
+bridge artifacts to the package abstraction. **Catalog** enriches packages
+with global security, legal, and operational metadata. **Evidence** attests
+to entities across all domains.
+
+## GraphQL (OneModel)
+
+For the unified **OneModel GraphQL** API (cross-product list/search over
+applications, packages, evidence, release bundles, catalog, and related
+entities on the platform base URL):
+
+- **Workflow** — mandatory per-server supergraph schema, validation, execution,
+  errors: `onemodel-graphql.md`
+- **Query templates and domain examples** — `onemodel-query-examples.md`
+- **Pagination, variables, date formats** — `onemodel-common-patterns.md`
+
+Also see **GraphQL (OneModel)** in the base `SKILL.md` (Tier 3 curl).
+
+## Entity lookup
+
+| Entity | Domain | Definition | Reference |
+|--------|--------|------------|-----------|
+| **Local repository** | Artifactory | Stores artifacts deployed directly (upload, promote, move) | `artifactory-entities.md` |
+| **Remote repository** | Artifactory | Proxy/cache for an external source; cached artifacts live in its `-cache` repo | `artifactory-entities.md` |
+| **Virtual repository** | Artifactory | Aggregates local and remote repos under a single resolution URL | `artifactory-entities.md` |
+| **Federated repository** | Artifactory | Local repo that synchronizes across multiple Platform Deployments | `artifactory-entities.md` |
+| **Artifact** | Artifactory | A file stored in a repository, identified by repo + path + name | `artifactory-entities.md` |
+| **Property** | Artifactory | Key-value metadata attached to an artifact or folder | `artifactory-entities.md` |
+| **Package type** | Artifactory | Repo-level setting that determines layout, metadata indexing, and client protocol | `artifactory-entities.md` |
+| **Build info** | Artifactory | Metadata record linking a CI/CD build to the artifacts it produced | `artifactory-entities.md` |
+| **Build promotion** | Artifactory | Status change on a build that can move/copy artifacts between repos | `artifactory-entities.md` |
+| **Permission** | Artifactory / Access | RBAC policy mapping resources (repos, builds, bundles, destinations) to user/group actions. V2 via Access, V1 (permission targets) via Artifactory | `artifactory-entities.md` |
+| **Replication** | Artifactory | Sync configuration that copies artifacts/properties between repos | `artifactory-entities.md` |
+| **Indexed resource** | Xray | A repository, build, or release bundle that Xray indexes for scanning | `xray-entities.md` |
+| **Component** | Xray | A software package identified and tracked by Xray during scanning | `xray-entities.md` |
+| **Vulnerability** | Xray | A known security issue (CVE) associated with a component version | `xray-entities.md` |
+| **Contextual analysis** | Xray | Assessment of whether a vulnerability is reachable in the usage context | `xray-entities.md` |
+| **License** | Xray | License metadata associated with a component, used for compliance policies | `xray-entities.md` |
+| **Watch** | Xray | Links resources (repos, builds) to policies for continuous monitoring | `xray-entities.md` |
+| **Policy** | Xray | Rules that evaluate components and produce violations when matched | `xray-entities.md` |
+| **Violation** | Xray | Generated when a component in a watched resource matches a policy rule | `xray-entities.md` |
+| **Ignore rule** | Xray | Suppresses specific violations by component, CVE, path, or other criteria | `xray-entities.md` |
+| **Exposure** | Xray (Advanced Security) | Actionable finding from exposures scanning — secrets, IaC issues, service misconfigurations, or application security risks detected in artifacts | `xray-entities.md` |
+| **Curation audit event** | Xray (Curation) | Record of a package check through a curated repository — approved or blocked, with policy details; supports dry-run analysis | `xray-entities.md` |
+| **Report** | Xray | On-demand security, license, or operational analysis over a defined scope | `xray-entities.md` |
+| **Release Bundle** | Release Lifecycle | Immutable, versioned collection of artifacts for promotion and distribution | `release-lifecycle-entities.md` |
+| **Lifecycle stage** | Release Lifecycle | Progression of a release bundle through environments (e.g. DEV → PROD) | `release-lifecycle-entities.md` |
+| **Distribution** | Release Lifecycle | Delivery of a release bundle to Edge nodes or other Platform Deployments | `release-lifecycle-entities.md` |
+| **Evidence** | Release Lifecycle | Cryptographic attestation attached to release bundles, apps, or packages (cross-domain) | `release-lifecycle-entities.md` |
+| **Evidence subject** | Release Lifecycle | Cross-domain anchor linking evidence to its target entity via `fullPath` | `release-lifecycle-entities.md` |
+| **Application** | AppTrust | Software application with versions, owners, criticality, and maturity level | `apptrust-entities.md` |
+| **Application version** | AppTrust | Versioned instance with releasables, sources, promotion history, and release status | `apptrust-entities.md` |
+| **Releasable** | AppTrust | Deployable unit within an app version — a package version or individual artifact | `apptrust-entities.md` |
+| **Application version promotion** | AppTrust | Stage-to-stage progression of an app version (with status tracking) | `apptrust-entities.md` |
+| **Application version source** | AppTrust | What produced releasables: Build, ReleaseBundle, ApplicationVersion, or Direct | `apptrust-entities.md` |
+| **Stored package** | Stored Packages | Package as known to Artifactory's metadata layer (name + type + versions) | `stored-packages-entities.md` |
+| **Stored package version** | Stored Packages | Specific version with locations, artifacts, tags, qualifiers, and stats | `stored-packages-entities.md` |
+| **Stored package version location** | Stored Packages | Where a package version lives (repo key + path) — bridge to Applications and Evidence | `stored-packages-entities.md` |
+| **Stored package artifact** | Stored Packages | Binary file within a package version (checksums, size, mime type) | `stored-packages-entities.md` |
+| **Public package** | Catalog | Package in JFrog's global database with security, legal, and operational metadata | `catalog-entities.md` |
+| **Public package version** | Catalog | Version with vulnerability, license, operational info, and dependencies | `catalog-entities.md` |
+| **Public vulnerability** | Catalog | CVE with CVSS v2/v3/v4, EPSS, advisories (NVD, GHSA, JFrog), known exploits | `catalog-entities.md` |
+| **Public license** | Catalog | License metadata with permissions, limitations, and patent conditions | `catalog-entities.md` |
+| **Custom package** | Catalog | Package in the organization's private catalog view with custom labels | `catalog-entities.md` |
+| **Custom catalog label** | Catalog | Organization-defined label for categorizing packages (manual or automatic) | `catalog-entities.md` |
+| **MCP service** | Catalog | Model Context Protocol service registered in the public catalog | `catalog-entities.md` |
+| **Project** | Platform / Access | Organizational container with its own members, roles, and resources | `platform-access-entities.md` |
+| **Project role** | Platform / Access | Per-project role definition scoping actions to environments | `platform-access-entities.md` |
+| **Project member** | Platform / Access | User or group assigned a role within a project | `platform-access-entities.md` |
+| **Environment** | Platform / Access | Groups resources and scopes RBAC; used in projects and release lifecycle | `platform-access-entities.md` |
+| **User** | Platform / Access | Platform identity that authenticates and is granted permissions | `platform-access-entities.md` |
+| **Group** | Platform / Access | Named collection of users; simplifies permission management | `platform-access-entities.md` |
+| **Access token** | Platform / Access | Bearer credential with scoped permissions and optional expiry | `platform-access-entities.md` |

package/skills/jfrog/references/jfrog-login-flow.md

@@ -0,0 +1,132 @@
+# Server Login Flow
+
+How to add or authenticate a JFrog Platform server. The agent drives this
+flow — the user only interacts via their browser.
+
+Requires Artifactory 7.64.0+ and the JFrog CLI (`jf`).
+
+## Security rules
+
+- Never print, echo, or display access tokens in terminal output or chat.
+- When confirming auth status, say "authenticated as user X" — never show
+the token.
+- `jf config` is the sole credential store. Never store tokens in files,
+env var profiles, or project directories.
+- Validate URLs with the ping endpoint before using them in shell commands.
+
+## Resolve the active environment
+
+```bash
+jf config show 2>/dev/null
+```
+
+- **0 servers** — ask the user for their JFrog Platform URL, then go to
+Web Login.
+- **1 server** — use it: `jf config use <server-id>`, done.
+- **2+ servers** — if the user named a specific server, use that one. Otherwise
+use the current default. If no default is set, list server IDs and URLs and
+ask the user which to use. **Never iterate through servers or fall back to
+another server on error** — see SKILL.md **Server selection rules**.
+
+## Web login (preferred)
+
+### 1. Verify server and register session
+
+```bash
+bash <skill_path>/scripts/jfrog-login-register-session.sh "https://mycompany.jfrog.io"
+```
+
+The script pings the server, generates a session UUID, and registers it with
+the Access API. On success it outputs:
+
+```
+SESSION_UUID=<uuid>
+VERIFY_CODE=<last 4 chars>
+```
+
+Exit codes: 0 = success, 2 = server unreachable, 3 = registration failed.
+
+### 2. Show the user the verification code and login link
+
+Build the login URL:
+
+```
+${JFROG_PLATFORM_URL}/ui/login?jfClientSession=${SESSION_UUID}&jfClientName=JFrog-Skills&jfClientCode=1
+```
+
+Show the verification code prominently, then the clickable link:
+
+> ## Verification code: `<last 4 chars of SESSION_UUID>`
+>
+> Open the login link from above, then enter the code.
+>
+> Let me know when you're done.
+
+Wait for the user to confirm. Do not poll automatically.
+
+### 3. Retrieve token, save credentials, verify
+
+```bash
+bash <skill_path>/scripts/jfrog-login-save-credentials.sh \
+  "https://mycompany.jfrog.io" \
+  "<SESSION_UUID from step 1>"
+```
+
+Substitute the literal platform URL and session UUID from step 1 output.
+
+The script retrieves the one-time token, derives a server ID from the URL,
+saves credentials via `jf config add`, and verifies with an Artifactory
+version check. It leaves the current default `jf` server unchanged — pass
+`--server-id=<id>` explicitly on subsequent calls (the SKILL.md "Server
+selection rules" require this anyway). On success it outputs:
+
+```
+SERVER_ID=<derived-id>
+--- Verifying authentication ---
+{ "version" : "7.x.x", ... }
+```
+
+Exit codes: 0 = success, 2 = token retrieval failed (user may not have
+completed browser login — HTTP 400), 3 = empty token, 4 = config save or
+verification failed.
+
+**The token endpoint is one-time-use.** If consumed (even in a failed save),
+the session UUID is invalidated and the flow must restart from step 1.
+
+## Post-login handoff (mandatory gate)
+
+Before any other JFrog operation against the new server, ask the user:
+
+> Logged in to `<SERVER_ID>`. Do you want to make it the default `jf`
+> server? (If you say no, I'll keep using `--server-id=<SERVER_ID>`
+> explicitly for follow-up calls.)
+
+- Confirm → `jf config use <SERVER_ID>`, then resume the original task.
+- Decline or no answer → keep `--server-id=<SERVER_ID>` on every `jf` call.
+
+## Fallback: manual token setup
+
+If web login fails (server too old, network restrictions):
+
+1. Ask the user to generate a token in the JFrog UI:
+  **Administration > Identity and Access > Access Tokens > Generate Token**
+2. Save it non-interactively:
+
+```bash
+jf config add <server-id> \
+  --url=https://<jfrog-url> \
+  --access-token=<token> \
+  --interactive=false
+```
+
+## Gotchas
+
+- The token endpoint (`/token/{uuid}`) is **one-time-use**. If consumed
+(even in a failed save), the session UUID is invalidated and the flow
+must restart from step 1. The save-credentials script handles cleanup,
+but if it exits non-zero after consuming the token, restart from step 1.
+- Server ID is derived from the hostname: `https://mycompany.jfrog.io`
+becomes `mycompany`. Self-hosted URLs are slugified:
+`https://artifactory.internal.corp` becomes `artifactory-internal-corp`.
+- `**jf`**, `**uuidgen**` (register-session), and `**jq**` (save-credentials) must be on PATH.
+