@aria_asi/cli 0.2.40 → 0.2.41

package/skills/playwright/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Playwright CLI Skill"
+  short_description: "Automate real browsers from the terminal"
+  icon_small: "./assets/playwright-small.svg"
+  icon_large: "./assets/playwright.png"
+  default_prompt: "Automate this browser workflow with Playwright and produce a reliable script with run steps."

package/skills/playwright/assets/playwright-small.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
+  <path d="m8.55 7.568.124.028 5.16 1.548.137.054c.606.294.645 1.165.068 1.512l-.133.066-2.236.894-.894 2.236c-.285.713-1.263.714-1.578.065l-.054-.138-1.548-5.16a.866.866 0 0 1 .954-1.105ZM10 12.983l.715-1.787.037-.08a.865.865 0 0 1 .445-.402L12.983 10 8.721 8.72l1.278 4.262ZM4.723 10.38a.532.532 0 0 1 .752.752l-1.414 1.414a.532.532 0 1 1-.752-.752l1.414-1.414ZM2.27 5.86l1.932.517.1.039a.533.533 0 0 1-.269 1.007l-.106-.018-1.932-.517-.101-.039a.532.532 0 0 1 .27-1.006l.106.017Zm9.608-2.62a.532.532 0 0 1 .668.82l-1.414 1.414a.532.532 0 1 1-.752-.752l1.414-1.414.084-.068ZM6.237 1.618a.532.532 0 0 1 .652.377l.518 1.932.017.106a.533.533 0 0 1-1.007.27l-.039-.101-.517-1.932-.017-.106a.532.532 0 0 1 .393-.546Z"/>
+</svg>

package/skills/playwright/references/cli.md

@@ -0,0 +1,116 @@
+# Playwright CLI Reference
+
+Use the wrapper script unless the CLI is already installed globally:
+
+```bash
+export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+export PWCLI="$CODEX_HOME/skills/playwright/scripts/playwright_cli.sh"
+"$PWCLI" --help
+```
+
+User-scoped skills install under `$CODEX_HOME/skills` (default: `~/.codex/skills`).
+
+Optional convenience alias:
+
+```bash
+alias pwcli="$PWCLI"
+```
+
+## Core
+
+```bash
+pwcli open https://example.com
+pwcli close
+pwcli snapshot
+pwcli click e3
+pwcli dblclick e7
+pwcli type "search terms"
+pwcli press Enter
+pwcli fill e5 "user@example.com"
+pwcli drag e2 e8
+pwcli hover e4
+pwcli select e9 "option-value"
+pwcli upload ./document.pdf
+pwcli check e12
+pwcli uncheck e12
+pwcli eval "document.title"
+pwcli eval "el => el.textContent" e5
+pwcli dialog-accept
+pwcli dialog-accept "confirmation text"
+pwcli dialog-dismiss
+pwcli resize 1920 1080
+```
+
+## Navigation
+
+```bash
+pwcli go-back
+pwcli go-forward
+pwcli reload
+```
+
+## Keyboard
+
+```bash
+pwcli press Enter
+pwcli press ArrowDown
+pwcli keydown Shift
+pwcli keyup Shift
+```
+
+## Mouse
+
+```bash
+pwcli mousemove 150 300
+pwcli mousedown
+pwcli mousedown right
+pwcli mouseup
+pwcli mouseup right
+pwcli mousewheel 0 100
+```
+
+## Save as
+
+```bash
+pwcli screenshot
+pwcli screenshot e5
+pwcli pdf
+```
+
+## Tabs
+
+```bash
+pwcli tab-list
+pwcli tab-new
+pwcli tab-new https://example.com/page
+pwcli tab-close
+pwcli tab-close 2
+pwcli tab-select 0
+```
+
+## DevTools
+
+```bash
+pwcli console
+pwcli console warning
+pwcli network
+pwcli run-code "await page.waitForTimeout(1000)"
+pwcli tracing-start
+pwcli tracing-stop
+```
+
+## Sessions
+
+Use a named session to isolate work:
+
+```bash
+pwcli --session todo open https://demo.playwright.dev/todomvc
+pwcli --session todo snapshot
+```
+
+Or set an environment variable once:
+
+```bash
+export PLAYWRIGHT_CLI_SESSION=todo
+pwcli open https://demo.playwright.dev/todomvc
+```

package/skills/playwright/references/workflows.md

@@ -0,0 +1,95 @@
+# Playwright CLI Workflows
+
+Use the wrapper script and snapshot often.
+Assume `PWCLI` is set and `pwcli` is an alias for `"$PWCLI"`.
+In this repo, run commands from `output/playwright/<label>/` to keep artifacts contained.
+
+## Standard interaction loop
+
+```bash
+pwcli open https://example.com
+pwcli snapshot
+pwcli click e3
+pwcli snapshot
+```
+
+## Form submission
+
+```bash
+pwcli open https://example.com/form --headed
+pwcli snapshot
+pwcli fill e1 "user@example.com"
+pwcli fill e2 "password123"
+pwcli click e3
+pwcli snapshot
+pwcli screenshot
+```
+
+## Data extraction
+
+```bash
+pwcli open https://example.com
+pwcli snapshot
+pwcli eval "document.title"
+pwcli eval "el => el.textContent" e12
+```
+
+## Debugging and inspection
+
+Capture console messages and network activity after reproducing an issue:
+
+```bash
+pwcli console warning
+pwcli network
+```
+
+Record a trace around a suspicious flow:
+
+```bash
+pwcli tracing-start
+# reproduce the issue
+pwcli tracing-stop
+pwcli screenshot
+```
+
+## Sessions
+
+Use sessions to isolate work across projects:
+
+```bash
+pwcli --session marketing open https://example.com
+pwcli --session marketing snapshot
+pwcli --session checkout open https://example.com/checkout
+```
+
+Or set the session once:
+
+```bash
+export PLAYWRIGHT_CLI_SESSION=checkout
+pwcli open https://example.com/checkout
+```
+
+## Configuration file
+
+By default, the CLI reads `playwright-cli.json` from the current directory. Use `--config` to point at a specific file.
+
+Minimal example:
+
+```json
+{
+  "browser": {
+    "launchOptions": {
+      "headless": false
+    },
+    "contextOptions": {
+      "viewport": { "width": 1280, "height": 720 }
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+- If an element ref fails, run `pwcli snapshot` again and retry.
+- If the page looks wrong, re-open with `--headed` and resize the window.
+- If a flow depends on prior state, use a named `--session`.

package/skills/playwright/scripts/playwright_cli.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if ! command -v npx >/dev/null 2>&1; then
+  echo "Error: npx is required but not found on PATH." >&2
+  exit 1
+fi
+
+has_session_flag="false"
+for arg in "$@"; do
+  case "$arg" in
+    --session|--session=*)
+      has_session_flag="true"
+      break
+      ;;
+  esac
+done
+
+cmd=(npx --yes --package @playwright/cli playwright-cli)
+if [[ "${has_session_flag}" != "true" && -n "${PLAYWRIGHT_CLI_SESSION:-}" ]]; then
+  cmd+=(--session "${PLAYWRIGHT_CLI_SESSION}")
+fi
+cmd+=("$@")
+
+exec "${cmd[@]}"

package/skills/plugin-creator/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: plugin-creator
+description: Create and scaffold plugin directories for Codex with a required `.codex-plugin/plugin.json`, optional plugin folders/files, and baseline placeholders you can edit before publishing or testing. Use when Codex needs to create a new local plugin, add optional plugin structure, or generate or update repo-root `.agents/plugins/marketplace.json` entries for plugin ordering and availability metadata.
+---
+
+# Plugin Creator
+
+## Quick Start
+
+1. Run the scaffold script:
+
+```bash
+  # Plugin names are normalized to lower-case hyphen-case and must be <= 64 chars.
+  # The generated folder and plugin.json name are always the same.
+# Run from repo root (or replace .agents/... with the absolute path to this SKILL).
+# By default creates in <repo_root>/plugins/<plugin-name>.
+python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py <plugin-name>
+```
+
+2. Open `<plugin-path>/.codex-plugin/plugin.json` and replace `[TODO: ...]` placeholders.
+
+3. Generate or update the repo marketplace entry when the plugin should appear in Codex UI ordering:
+
+```bash
+# marketplace.json always lives at <repo-root>/.agents/plugins/marketplace.json
+python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin --with-marketplace
+```
+
+For a home-local plugin, treat `<home>` as the root and use:
+
+```bash
+python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin \
+  --path ~/plugins \
+  --marketplace-path ~/.agents/plugins/marketplace.json \
+  --with-marketplace
+```
+
+4. Generate/adjust optional companion folders as needed:
+
+```bash
+python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin --path <parent-plugin-directory> \
+  --with-skills --with-hooks --with-scripts --with-assets --with-mcp --with-apps --with-marketplace
+```
+
+`<parent-plugin-directory>` is the directory where the plugin folder `<plugin-name>` will be created (for example `~/code/plugins`).
+
+## What this skill creates
+
+- If the user has not made the plugin location explicit, ask whether they want a repo-local plugin or a home-local plugin before generating marketplace entries.
+- Creates plugin root at `/<parent-plugin-directory>/<plugin-name>/`.
+- Always creates `/<parent-plugin-directory>/<plugin-name>/.codex-plugin/plugin.json`.
+- Fills the manifest with the full schema shape, placeholder values, and the complete `interface` section.
+- Creates or updates `<repo-root>/.agents/plugins/marketplace.json` when `--with-marketplace` is set.
+  - If the marketplace file does not exist yet, seed top-level `name` plus `interface.displayName` placeholders before adding the first plugin entry.
+- `<plugin-name>` is normalized using skill-creator naming rules:
+  - `My Plugin` → `my-plugin`
+  - `My--Plugin` → `my-plugin`
+  - underscores, spaces, and punctuation are converted to `-`
+  - result is lower-case hyphen-delimited with consecutive hyphens collapsed
+- Supports optional creation of:
+  - `skills/`
+  - `hooks/`
+  - `scripts/`
+  - `assets/`
+  - `.mcp.json`
+  - `.app.json`
+
+## Marketplace workflow
+
+- `marketplace.json` always lives at `<repo-root>/.agents/plugins/marketplace.json`.
+- For a home-local plugin, use the same convention with `<home>` as the root:
+  `~/.agents/plugins/marketplace.json` plus `./plugins/<plugin-name>`.
+- Marketplace root metadata supports top-level `name` plus optional `interface.displayName`.
+- Treat plugin order in `plugins[]` as render order in Codex. Append new entries unless a user explicitly asks to reorder the list.
+- `displayName` belongs inside the marketplace `interface` object, not individual `plugins[]` entries.
+- Each generated marketplace entry must include all of:
+  - `policy.installation`
+  - `policy.authentication`
+  - `category`
+- Default new entries to:
+  - `policy.installation: "AVAILABLE"`
+  - `policy.authentication: "ON_INSTALL"`
+- Override defaults only when the user explicitly specifies another allowed value.
+- Allowed `policy.installation` values:
+  - `NOT_AVAILABLE`
+  - `AVAILABLE`
+  - `INSTALLED_BY_DEFAULT`
+- Allowed `policy.authentication` values:
+  - `ON_INSTALL`
+  - `ON_USE`
+- Treat `policy.products` as an override. Omit it unless the user explicitly requests product gating.
+- The generated plugin entry shape is:
+
+```json
+{
+  "name": "plugin-name",
+  "source": {
+    "source": "local",
+    "path": "./plugins/plugin-name"
+  },
+  "policy": {
+    "installation": "AVAILABLE",
+    "authentication": "ON_INSTALL"
+  },
+  "category": "Productivity"
+}
+```
+
+- Use `--force` only when intentionally replacing an existing marketplace entry for the same plugin name.
+- If `<repo-root>/.agents/plugins/marketplace.json` does not exist yet, create it with top-level `"name"`, an `"interface"` object containing `"displayName"`, and a `plugins` array, then add the new entry.
+
+- For a brand-new marketplace file, the root object should look like:
+
+```json
+{
+  "name": "[TODO: marketplace-name]",
+  "interface": {
+    "displayName": "[TODO: Marketplace Display Name]"
+  },
+  "plugins": [
+    {
+      "name": "plugin-name",
+      "source": {
+        "source": "local",
+        "path": "./plugins/plugin-name"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}
+```
+
+## Required behavior
+
+- Outer folder name and `plugin.json` `"name"` are always the same normalized plugin name.
+- Do not remove required structure; keep `.codex-plugin/plugin.json` present.
+- Keep manifest values as placeholders until a human or follow-up step explicitly fills them.
+- If creating files inside an existing plugin path, use `--force` only when overwrite is intentional.
+- Preserve any existing marketplace `interface.displayName`.
+- When generating marketplace entries, always write `policy.installation`, `policy.authentication`, and `category` even if their values are defaults.
+- Add `policy.products` only when the user explicitly asks for that override.
+- Keep marketplace `source.path` relative to repo root as `./plugins/<plugin-name>`.
+
+## Reference to exact spec sample
+
+For the exact canonical sample JSON for both plugin manifests and marketplace entries, use:
+
+- `references/plugin-json-spec.md`
+
+## Validation
+
+After editing `SKILL.md`, run:
+
+```bash
+python3 <path-to-skill-creator>/scripts/quick_validate.py .agents/skills/plugin-creator
+```
+
+## Required Workflow
+
+1. Identify the plugin surface, manifest type, and install target.
+2. Use the canonical manifest schema and local templates where available.
+3. Validate the generated plugin or marketplace entry before delivery.
+4. Check that referenced skills, commands, and paths exist.
+5. Report generated files, validation result, and remaining manual steps.
+
+## First-Class Production Contract
+
+When this skill is loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, and no vague future wiring in plugin manifests or generated files
+- real proof from schema validation, local file checks, command output, or owner instruction before claiming readiness
+- re-test or re-check the same plugin surface after correction
+- a redo contract whenever plugin validation fails: state what failed, what changed, how it was re-tested, and the remaining blocker
+- architect/ARIA console escalation when the same plugin failure repeats twice, crosses system boundaries, or cannot be verified locally

package/skills/plugin-creator/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Plugin Creator"
+  short_description: "Scaffold plugins and marketplace entries"
+  default_prompt: "Use $plugin-creator to scaffold a plugin with placeholder plugin.json, optional structure, and a marketplace.json entry."
+  icon_small: "./assets/plugin-creator-small.svg"
+  icon_large: "./assets/plugin-creator.png"

package/skills/plugin-creator/assets/plugin-creator-small.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" fill="currentColor" viewBox="0 0 20 20">
+  <path fill="#0D0D0D" d="M12.03 4.113a3.612 3.612 0 0 1 5.108 5.108l-6.292 6.29c-.324.324-.56.561-.791.752l-.235.176c-.205.14-.422.261-.65.36l-.229.093a4.136 4.136 0 0 1-.586.16l-.764.134-2.394.4c-.142.024-.294.05-.423.06-.098.007-.232.01-.378-.026l-.149-.05a1.081 1.081 0 0 1-.521-.474l-.046-.093a1.104 1.104 0 0 1-.075-.527c.01-.129.035-.28.06-.422l.398-2.394c.1-.602.162-.987.295-1.35l.093-.23c.1-.228.22-.445.36-.65l.176-.235c.19-.232.428-.467.751-.79l6.292-6.292Zm-5.35 7.232c-.35.35-.534.535-.66.688l-.11.147a2.67 2.67 0 0 0-.24.433l-.062.154c-.08.22-.124.462-.232 1.112l-.398 2.394-.001.001h.003l2.393-.399.717-.126a2.63 2.63 0 0 0 .394-.105l.154-.063a2.65 2.65 0 0 0 .433-.24l.147-.11c.153-.126.339-.31.688-.66l4.988-4.988-3.227-3.226-4.987 4.988Zm9.517-6.291a2.281 2.281 0 0 0-3.225 0l-.364.362 3.226 3.227.363-.364c.89-.89.89-2.334 0-3.225ZM4.583 1.783a.3.3 0 0 1 .294.241c.117.585.347 1.092.707 1.48.357.385.859.668 1.549.783a.3.3 0 0 1 0 .592c-.69.115-1.192.398-1.549.783-.315.34-.53.77-.657 1.265l-.05.215a.3.3 0 0 1-.588 0c-.117-.585-.347-1.092-.707-1.48-.357-.384-.859-.668-1.549-.783a.3.3 0 0 1 0-.592c.69-.115 1.192-.398 1.549-.783.36-.388.59-.895.707-1.48l.015-.05a.3.3 0 0 1 .279-.19Z"/>
+</svg>

package/skills/plugin-creator/references/plugin-json-spec.md

@@ -0,0 +1,170 @@
+# Plugin JSON sample spec
+
+```json
+{
+  "name": "plugin-name",
+  "version": "1.2.0",
+  "description": "Brief plugin description",
+  "author": {
+    "name": "Author Name",
+    "email": "author@example.com",
+    "url": "https://github.com/author"
+  },
+  "homepage": "https://docs.example.com/plugin",
+  "repository": "https://github.com/author/plugin",
+  "license": "MIT",
+  "keywords": ["keyword1", "keyword2"],
+  "skills": "./skills/",
+  "hooks": "./hooks.json",
+  "mcpServers": "./.mcp.json",
+  "apps": "./.app.json",
+  "interface": {
+    "displayName": "Plugin Display Name",
+    "shortDescription": "Short description for subtitle",
+    "longDescription": "Long description for details page",
+    "developerName": "OpenAI",
+    "category": "Productivity",
+    "capabilities": ["Interactive", "Write"],
+    "websiteURL": "https://openai.com/",
+    "privacyPolicyURL": "https://openai.com/policies/row-privacy-policy/",
+    "termsOfServiceURL": "https://openai.com/policies/row-terms-of-use/",
+    "defaultPrompt": [
+      "Summarize my inbox and draft replies for me.",
+      "Find open bugs and turn them into Linear tickets.",
+      "Review today's meetings and flag scheduling gaps."
+    ],
+    "brandColor": "#3B82F6",
+    "composerIcon": "./assets/icon.png",
+    "logo": "./assets/logo.png",
+    "screenshots": [
+      "./assets/screenshot1.png",
+      "./assets/screenshot2.png",
+      "./assets/screenshot3.png"
+    ]
+  }
+}
+```
+
+## Field guide
+
+### Top-level fields
+
+- `name` (`string`): Plugin identifier (kebab-case, no spaces). Required if `plugin.json` is provided and used as manifest name and component namespace.
+- `version` (`string`): Plugin semantic version.
+- `description` (`string`): Short purpose summary.
+- `author` (`object`): Publisher identity.
+  - `name` (`string`): Author or team name.
+  - `email` (`string`): Contact email.
+  - `url` (`string`): Author/team homepage or profile URL.
+- `homepage` (`string`): Documentation URL for plugin usage.
+- `repository` (`string`): Source code URL.
+- `license` (`string`): License identifier (for example `MIT`, `Apache-2.0`).
+- `keywords` (`array` of `string`): Search/discovery tags.
+- `skills` (`string`): Relative path to skill directories/files.
+- `hooks` (`string`): Hook config path.
+- `mcpServers` (`string`): MCP config path.
+- `apps` (`string`): App manifest path for plugin integrations.
+- `interface` (`object`): Interface/UX metadata block for plugin presentation.
+
+### `interface` fields
+
+- `displayName` (`string`): User-facing title shown for the plugin.
+- `shortDescription` (`string`): Brief subtitle used in compact views.
+- `longDescription` (`string`): Longer description used on details screens.
+- `developerName` (`string`): Human-readable publisher name.
+- `category` (`string`): Plugin category bucket.
+- `capabilities` (`array` of `string`): Capability list from implementation.
+- `websiteURL` (`string`): Public website for the plugin.
+- `privacyPolicyURL` (`string`): Privacy policy URL.
+- `termsOfServiceURL` (`string`): Terms of service URL.
+- `defaultPrompt` (`array` of `string`): Starter prompts shown in composer/UX context.
+  - Include at most 3 strings. Entries after the first 3 are ignored and will not be included.
+  - Each string is capped at 128 characters. Longer entries are truncated.
+  - Prefer short starter prompts around 50 characters so they scan well in the UI.
+- `brandColor` (`string`): Theme color for the plugin card.
+- `composerIcon` (`string`): Path to icon asset.
+- `logo` (`string`): Path to logo asset.
+- `screenshots` (`array` of `string`): List of screenshot asset paths.
+  - Screenshot entries must be PNG filenames and stored under `./assets/`.
+  - Keep file paths relative to plugin root.
+
+### Path conventions and defaults
+
+- Path values should be relative and begin with `./`.
+- `skills`, `hooks`, and `mcpServers` are supplemented on top of default component discovery; they do not replace defaults.
+- Custom path values must follow the plugin root convention and naming/namespacing rules.
+- This repo’s scaffold writes `.codex-plugin/plugin.json`; treat that as the manifest location this skill generates.
+
+# Marketplace JSON sample spec
+
+`marketplace.json` depends on where the plugin should live:
+
+- Repo plugin: `<repo-root>/.agents/plugins/marketplace.json`
+- Local plugin: `~/.agents/plugins/marketplace.json`
+
+```json
+{
+  "name": "openai-curated",
+  "interface": {
+    "displayName": "ChatGPT Official"
+  },
+  "plugins": [
+    {
+      "name": "linear",
+      "source": {
+        "source": "local",
+        "path": "./plugins/linear"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}
+```
+
+## Marketplace field guide
+
+### Top-level fields
+
+- `name` (`string`): Marketplace identifier or catalog name.
+- `interface` (`object`, optional): Marketplace presentation metadata.
+- `plugins` (`array`): Ordered plugin entries. This order determines how Codex renders plugins.
+
+### `interface` fields
+
+- `displayName` (`string`, optional): User-facing marketplace title.
+
+### Plugin entry fields
+
+- `name` (`string`): Plugin identifier. Match the plugin folder name and `plugin.json` `name`.
+- `source` (`object`): Plugin source descriptor.
+  - `source` (`string`): Use `local` for this repo workflow.
+  - `path` (`string`): Relative plugin path based on the marketplace root.
+    - Repo plugin: `./plugins/<plugin-name>`
+    - Local plugin in `~/.agents/plugins/marketplace.json`: `./plugins/<plugin-name>`
+  - The same relative path convention is used for both repo-rooted and home-rooted marketplaces.
+    - Example: with `~/.agents/plugins/marketplace.json`, `./plugins/<plugin-name>` resolves to `~/plugins/<plugin-name>`.
+- `policy` (`object`): Marketplace policy block. Always include it.
+  - `installation` (`string`): Availability policy.
+    - Allowed values: `NOT_AVAILABLE`, `AVAILABLE`, `INSTALLED_BY_DEFAULT`
+    - Default for new entries: `AVAILABLE`
+  - `authentication` (`string`): Authentication timing policy.
+    - Allowed values: `ON_INSTALL`, `ON_USE`
+    - Default for new entries: `ON_INSTALL`
+  - `products` (`array` of `string`, optional): Product override for this plugin entry. Omit it unless product gating is explicitly requested.
+- `category` (`string`): Display category bucket. Always include it.
+
+### Marketplace generation rules
+
+- `displayName` belongs under the top-level `interface` object, not individual plugin entries.
+- When creating a new marketplace file from scratch, seed `interface.displayName` alongside top-level `name`.
+- Always include `policy.installation`, `policy.authentication`, and `category` on every generated or updated plugin entry.
+- Treat `policy.products` as an override and omit it unless explicitly requested.
+- Append new entries unless the user explicitly requests reordering.
+- Replace an existing entry for the same plugin only when overwrite is intentional.
+- Choose marketplace location to match the plugin destination:
+  - Repo plugin: `<repo-root>/.agents/plugins/marketplace.json`
+  - Local plugin: `~/.agents/plugins/marketplace.json`