byob-cli 0.2.9

package/skills/byob_cli/SKILL.md

@@ -0,0 +1,423 @@
+---
+name: byob_cli
+description: Use BYOB CLI as the Codex connector for deployed/production BYOB projects, including OAuth approval, scoped project access, coding tools, deployment, billing, and safe remote editing.
+aliases:
+  - byob
+  - byob mcp
+  - byob deployed mcp
+  - production byob_cli
+---
+
+# BYOB CLI Skill
+
+Use this when Codex connects to a BYOB-hosted project through BYOB CLI. Other MCP-capable coding agents can use the same bridge, but Codex is the first-class workflow. This skill is for production-like hosted BYOB projects, not local developer stack debugging or local repository editing.
+
+Critical boundary: BYOB CLI tools operate on a remote BYOB project container selected by the approved BYOB agent token. They must not be used to inspect, edit, test, commit, or deploy the local filesystem/repository where Codex itself is running. For local files such as the current checkout, use Codex's normal local file and shell tools instead. Use BYOB CLI only when the user explicitly wants Codex to work inside a BYOB platform project, or when the active task clearly references a BYOB project id/context.
+
+For substantial BYOB project coding work, also read `CODEX_CORE.md` from this skill directory. It is the Codex-specific platform contract for direct project editing: project context, tool routing, protected BYOB files, testing expectations, deployment/domain/analytics behavior, billing URL handling, and security boundaries. It is not the reusable UI/style guide.
+
+BYOB projects include platform-managed content mixed into normal app files. Keep this protected-file instruction in context at session start or before the first project-file edit. This does not mean loading protected file contents by default. Preserve BYOB preview/editor/HMR connectors, platform script tags, injected placeholders, route indexes, LLM/agent helper files, env restore/sync glue, deployment scripts, and package/dev-server metadata unless the user explicitly asks to modify that platform behavior. When editing a protected file, change only the user-owned section needed for the task.
+
+At the start of a BYOB coding session, and whenever switching projects, establish context with `_meta.byob_project`, resource `byob://project/<project_id>/context`, `byob_current_project_context`, or `byob context`. Tell the user the project name, project id, and preview URL before project-specific edits when the active project was not already clear.
+
+After authentication, the installer downloads BYOB AIR coding skills into local Codex skill folders named with `byob_` prefixes. Use those synced `byob_*` skills for SvelteKit, Supabase, BYOB DB, UI quality, testing, SEO, PWA, payments, animations, image generation, and related implementation patterns. Pass `--no-air-skills` only if the user wants the MCP server and core platform skill without reusable coding skills.
+
+Do not load `CODEX_CORE.md` for a simple account/status/payment-link lookup.
+
+## Core Model
+
+BYOB has two MCP surfaces:
+
+- **Agent MCP**: hosted by AIR, user-facing, OAuth protected, safe for external coding agents.
+- **Container MCP**: private per-project executor inside the running project container.
+
+External agents connect only to **Agent MCP**. AIR validates the agent token, checks project scope, starts projects when needed, and proxies coding tools into the private container MCP.
+
+Never ask users for raw `mcp_token`, `mcp_env_sec_token`, editor tokens, preview tokens, Git tokens, or service-role keys.
+
+## Deployed OAuth Device Flow
+
+Prefer the packaged helper when running from a user machine:
+
+```bash
+npx -y byob-cli codex install --client-name "Codex"
+```
+
+This starts the device flow, waits for browser approval, and configures Codex MCP in one command.
+It also installs this skill into `~/.agents/skills/byob_cli`; restart Codex or start a new session if the skill list was already open.
+After authentication, the installer downloads BYOB AIR coding skills into local Codex skill folders named with `byob_` prefixes.
+
+Refresh downloaded coding skills later without rerunning OAuth or changing MCP config:
+
+```bash
+npx -y byob-cli codex sync-skills --project-id <project_id> --token <agent_access_token>
+```
+
+Equivalent raw PRIM flow:
+
+1. Request a device code from PRIM:
+
+```http
+POST /oauth/device/code
+Content-Type: application/json
+
+{
+  "client_name": "Your agent name"
+}
+```
+
+2. Show the user:
+
+- `user_code`
+- `verification_uri_complete`
+
+3. User signs in through BYOB and approves selected projects.
+
+4. Poll PRIM:
+
+```http
+POST /oauth/token
+Content-Type: application/json
+
+{
+  "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+  "device_code": "<device_code>"
+}
+```
+
+Handle:
+
+- `authorization_pending`: poll again using the returned interval.
+- `access_denied`: stop; user rejected the connection.
+- `expired_token`: restart device flow.
+- success: store `access_token` and `refresh_token` securely.
+
+The grant can include multiple project ids. If the agent needs another project later, restart device flow and ask the user to approve that project too.
+
+## Token Lifetime And Refresh
+
+Access tokens are intentionally long enough for normal coding sessions. Refresh tokens are long lived and rotate on use.
+
+When an MCP call returns token expiration, refresh:
+
+```http
+POST /oauth/token
+Content-Type: application/json
+
+{
+  "grant_type": "refresh_token",
+  "refresh_token": "<refresh_token>"
+}
+```
+
+Replace both stored tokens from the response. Never print tokens in chat, logs, telemetry, errors, or screenshots.
+
+## Agent MCP Endpoint
+
+Connect to the deployed AIR broker:
+
+```text
+/mcp/projects/<project_id>
+```
+
+Send:
+
+```http
+Authorization: Bearer <agent_access_token>
+```
+
+Use JSON-RPC MCP methods:
+
+- `initialize`
+- `tools/list`
+- `tools/call`
+- `ping`
+
+## Production URL Rules
+
+In deployed BYOB, configure control-plane hosts explicitly:
+
+- `BYOB_AIR_URL`: deployed AIR Agent MCP broker, always `https://air.api.byob.studio` in production.
+- `--prim-url` / `BYOB_PRIM_URL`: deployed PRIM OAuth/token API, always `https://prim.api.byob.studio` in production.
+
+The packaged helper defaults to those production hosts. Pass URL overrides only for local development or staging.
+
+Never infer preview, editor, or deployment URLs from local ports or hostnames. Standard production project runtime URLs normally use these host patterns:
+
+- Editor: `https://editor.<project_id>.api.byob.studio`
+- Preview: `https://preview.<project_id>.api.byob.studio`
+
+Use those patterns only as production shape guidance. Production project URLs are platform-generated and may differ by deployment, gateway, or custom-domain state. Read the actual URL from:
+
+- `byob_current_project_context`
+- `byob context`
+- `_meta.byob_project`
+- `byob_deployment_status` for deployment/canonical URLs
+
+Treat `editor_url` as a session-sensitive link. Surface it only when the user or host UI needs it.
+
+For local scripts, CI smoke checks, or agents that do not have a native MCP client yet, use the packaged helper instead of constructing JSON-RPC by hand:
+
+```bash
+BYOB_AGENT_TOKEN=<agent_access_token> BYOB_PROJECT_ID=<project_id> \
+byob tools
+```
+
+Shortcut commands include `status`, `start`, `deploy`, `env-status`, `grants`, and `dns`.
+
+Use `byob context` or MCP tool `byob_current_project_context` when Codex needs project name/id/status/preview/editor/deployment metadata. Host UIs can also render resource `byob://project/<project_id>/context` or `_meta.byob_project` outside model-visible text.
+
+For MCP clients that use local stdio servers, configure the npm package in the standard `mcpServers` shape:
+
+```json
+{
+  "mcpServers": {
+    "byob": {
+      "command": "npx",
+      "args": ["-y", "byob-cli", "mcp"],
+      "env": {
+        "BYOB_PROJECT_ID": "<project_id>",
+        "BYOB_AGENT_TOKEN": "<agent_access_token>"
+      }
+    }
+  }
+}
+```
+
+For multiple approved projects, prefer one named MCP server per project when the client UI supports multiple servers. This makes tool use less ambiguous and avoids relying on the model to pass `project_id` correctly:
+
+```json
+{
+  "mcpServers": {
+    "byob-web": {
+      "command": "npx",
+      "args": ["-y", "byob-cli", "mcp"],
+      "env": {
+        "BYOB_PROJECT_ID": "<web_project_id>",
+        "BYOB_AGENT_TOKEN": "<agent_access_token>"
+      }
+    },
+    "byob-admin": {
+      "command": "npx",
+      "args": ["-y", "byob-cli", "mcp"],
+      "env": {
+        "BYOB_PROJECT_ID": "<admin_project_id>",
+        "BYOB_AGENT_TOKEN": "<agent_access_token>"
+      }
+    }
+  }
+}
+```
+
+If the client needs a single MCP entry, run `byob mcp --multi-project` with `BYOB_PROJECT_IDS`:
+
+```json
+{
+  "mcpServers": {
+    "byob": {
+      "command": "npx",
+      "args": ["-y", "byob-cli", "mcp", "--multi-project"],
+      "env": {
+        "BYOB_PROJECT_IDS": "<project_id_1>,<project_id_2>",
+        "BYOB_CLI_MULTI_PROJECT": "1",
+        "BYOB_AGENT_TOKEN": "<agent_access_token>"
+      }
+    }
+  }
+}
+```
+
+In multi-project mode, every project-specific tool call should include `project_id` in `arguments`; otherwise the first configured project is the default. Project switching is explicit; the helper does not persist a mutable current project.
+
+For project context in multi-project mode, call:
+
+```bash
+byob context '{"project_id":"<project_id>"}'
+```
+
+or read resource URI `byob://project/<project_id>/context`.
+
+## Tool Routing
+
+BYOB helper tools are exposed through Agent MCP. AIR handles token/project-scope validation; PRIM owns project-management behavior such as start, deploy, analytics, and custom domains.
+
+- `byob_list_projects`
+- `byob_current_project_context`
+- `byob_project_status`
+- `byob_start_project`
+- `byob_billing_status`
+- `byob_payment_url`
+- `byob_project_env_status`
+- `byob_list_agent_grants`
+- `byob_revoke_agent_grant`
+- `byob_deploy_project`
+- `byob_deployment_status`
+- `byob_deployment_analytics`
+- `byob_get_custom_domain`
+- `byob_custom_domain_dns_instructions`
+- `byob_set_custom_domain`
+- `byob_delete_custom_domain`
+- `byob_testing_browsers`
+- `byob_browser_session_start`
+- `byob_browser_action`
+- `byob_browser_session_close`
+
+Coding tools are proxied by AIR into the private project container MCP:
+
+- file tree, read, search, edit, write, move, copy, delete
+- Git status/diff operations exposed by the coding tool surface
+- package add/remove
+- preview, browser, and MCP logs
+- database/environment helpers that BYOB exposes for that project
+
+Do not assume `byob_*` tools exist inside the user container. They are platform tools and belong to Agent MCP only.
+
+## Project Scope
+
+The user approves specific projects during browser approval. The agent token can only access those project ids.
+
+If a project was not selected:
+
+1. Call `byob_list_projects`.
+2. If the needed project is absent, ask the user to reconnect and approve it.
+
+AIR rechecks BYOB access on every call. If access is revoked, stop using that project and ask the user to reconnect or update sharing.
+
+For multiple projects:
+
+- Use `byob_list_projects` or `byob projects` to discover approved ids.
+- Prefer one MCP server entry per project for coding tasks.
+- In multi-project mode, include `project_id` for `byob_*` project tools and coding tools.
+- If a tool acts on the wrong project, stop and retry with explicit `project_id`.
+
+## Project Context Display
+
+Expose the current project context in host UI rather than chat text:
+
+- Tool: `byob_current_project_context`.
+- Resource: `byob://project/<project_id>/context`.
+- CLI: `byob context`.
+- Metadata: `_meta.byob_project` on initialize/tools/resource responses.
+
+Codex reliably sees the tool and receives BYOB CLI MCP server instructions telling it to use the tool when context is needed. Resources and `_meta` are best for clients/hosts that render them out of band.
+
+The payload includes project name, id, status, preview URL, editor URL, deployment URL, publish slug, and timestamps. Treat editor URLs as user/session-sensitive and do not log them casually.
+
+## Startup And Readiness
+
+If a project is stopped, AIR may auto-start it before running coding tools. Startup can be slow.
+
+Recommended flow:
+
+1. Call `byob_project_status`.
+2. If stopped, call `byob_start_project` or let the first coding tool auto-start.
+3. Retry coding tools only for transient startup/readiness errors.
+4. Do not loop indefinitely. Surface persistent startup failures with the BYOB error message and payment URL if provided.
+
+## Credits And Payment URLs
+
+If credits block project startup or usage, Agent MCP returns a structured billing error and may include a `payment_url`.
+
+Expected billing/startup errors:
+
+- `INSUFFICIENT_CREDITS`
+- `PROJECT_START_FAILED`
+- `QUOTA_EXCEEDED`
+
+Use:
+
+- `byob_billing_status` to inspect balance/plan.
+- `byob_payment_url` to generate a clickable BYOB billing link.
+- CLI aliases: `byob billing` and `byob payment-url '{"topup":500}'`.
+
+Surface BYOB payment URLs directly to the user. Do not create checkout links yourself, collect payment details, or ask for card data.
+
+## Deployment
+
+Use PRIM-owned deployment helpers through Agent MCP:
+
+1. Call `byob_deployment_status`.
+2. If the project is stopped, call `byob_start_project` or let `byob_deploy_project` start it if supported.
+3. Verify coding tools and preview logs if deployment needs a fresh build.
+4. Call `byob_deploy_project`.
+5. Call `byob_deployment_status` again and surface `deployment_url` or `byob_url`.
+
+Deployment failures may come from credits/quota, project startup, preview build export, Cloudflare Worker deploy, D1 bindings, or env bindings. Report the failing layer and the returned PRIM message.
+
+Do not ask users for Cloudflare tokens or call Cloudflare directly. BYOB deployment credentials stay in PRIM/platform infrastructure.
+
+## Custom Domains And Analytics
+
+Custom-domain tools are PRIM-owned and feature-gated:
+
+- `byob_get_custom_domain`: inspect current domain, SSL status, and DNS verification payload.
+- `byob_set_custom_domain`: attach a hostname after the project is deployed.
+- `byob_custom_domain_dns_instructions`: return exact DNS records and HTTP challenges to show the user.
+- `byob_delete_custom_domain`: remove the current hostname.
+
+If `byob_set_custom_domain` or `byob_custom_domain_dns_instructions` returns DNS records, show them exactly as returned. Do not invent CNAME/TXT values.
+
+Use `byob_deployment_analytics` only after the project is deployed. If there is no publish slug yet, deploy first.
+
+## Env And Grant Helpers
+
+Use `byob_project_env_status` before deploy troubleshooting. It returns key names, value presence, public/client-only flags, and Worker binding eligibility without exposing secret values.
+
+Use `byob_list_agent_grants` and `byob_revoke_agent_grant` for user-visible connection management. Revoking the current grant will invalidate the active agent session; after that, restart OAuth device flow.
+
+## Codex-Driven Browser Testing
+
+BYOB has two testing modes:
+
+- BYOB app testing modal: internally driven by BYOB AIR's testing agent.
+- Direct Codex checks: Codex can fetch or inspect the project preview URL directly when HTTP/page content checks are enough.
+- Agent MCP browser tools: driven directly by Codex through the connected BYOB browser extension when real browser interaction is needed.
+
+Prefer the cheapest sufficient testing path:
+
+1. For basic smoke checks, fetch/read the `preview_url` directly with the available fetch/browser tools in the Codex environment.
+2. Use project log tools such as `read_vite_preview_server_logs` and `read_browser_console_logs` for runtime errors already captured by BYOB.
+3. Use BYOB browser-extension tools only when Codex needs live browser state: screenshots, clicks, typing, viewport checks, DOM evaluation in the real page, console logs from a fresh session, or network capture.
+
+For Codex-driven testing, do not call `delegate_testing`; that is a BYOB chat UI tool and is not exposed through Agent MCP. Use:
+
+1. `byob_testing_browsers` to find connected browser extension devices scoped to the approved user/project.
+2. `byob_browser_session_start` to claim one browser and open the preview URL.
+3. `byob_browser_action` for `navigate`, `screenshot`, `click`, `type`, `evaluate`, `wait_for_selector`, `resize_viewport`, `get_console_logs`, `start_network_capture`, `get_network_log`, and `clear_network_log`.
+4. `byob_browser_session_close` when finished.
+
+If no browser is connected, tell the user to install or open the BYOB Testing extension:
+
+```text
+https://chromewebstore.google.com/detail/byob-testing/ncnaebcfklfpcapminohoiekcemmaalj
+```
+
+When a task will need visual/browser testing and another long-running step is underway, such as image generation, package install, build, or deploy, tell the user early that installing the extension during that wait will let Codex test the preview afterward.
+
+When testing UI changes, take screenshots for important states, inspect console logs, and report the preview URL with pass/fail findings.
+
+## Editing And Verification
+
+For code edits:
+
+1. Read the file first.
+2. Use `edit_file` for targeted changes or `write_file` for complete small-file rewrites.
+3. Read the file back.
+4. Verify with available tools, commonly:
+   - `execute_git_command ["diff", "--", "<path>"]`
+   - `execute_git_command ["status", "--short"]`
+   - preview/server log tools
+   - live preview fetch when the URL is available
+5. After successful code changes, show the current preview URL to the user. Prefer the `preview_url` returned by the mutating tool response metadata or call `byob_current_project_context` if needed.
+
+If no general shell tool is exposed, do not invent one. Use the tools returned by `tools/list`.
+
+## Safety
+
+- Never request or expose internal BYOB/container secrets.
+- Never log bearer tokens.
+- Never add BYOB platform helper tools to user containers.
+- Keep user project changes scoped to the approved project.
+- Use `byob_*` tools only for account/project/billing/deployment operations.
+- Use coding tools only for project-local filesystem/runtime operations.
+- On repeated connection/start failures, report the concrete failing layer: OAuth, AIR, PRIM, Conman/startup, Git/repo, runner MCP readiness, or coding tool execution.