natureco-cli 5.18.2 → 5.19.0

package/skills/ubiquitous-language/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: ubiquitous-language
+description: Extract a DDD-style ubiquitous language glossary from the current conversation, flagging ambiguities and proposing canonical terms. Saves to UBIQUITOUS_LANGUAGE.md. Use when user wants to define domain terms, build a glossary, harden terminology, create a ubiquitous language, or mentions "domain model" or "DDD".
+disable-model-invocation: true
+---
+
+# Ubiquitous Language
+
+Extract and formalize domain terminology from the current conversation into a consistent glossary, saved to a local file.
+
+## Process
+
+1. **Scan the conversation** for domain-relevant nouns, verbs, and concepts
+2. **Identify problems**:
+   - Same word used for different concepts (ambiguity)
+   - Different words used for the same concept (synonyms)
+   - Vague or overloaded terms
+3. **Propose a canonical glossary** with opinionated term choices
+4. **Write to `UBIQUITOUS_LANGUAGE.md`** in the working directory using the format below
+5. **Output a summary** inline in the conversation
+
+## Output Format
+
+Write a `UBIQUITOUS_LANGUAGE.md` file with this structure:
+
+```md
+# Ubiquitous Language
+
+## Order lifecycle
+
+| Term        | Definition                                              | Aliases to avoid      |
+| ----------- | ------------------------------------------------------- | --------------------- |
+| **Order**   | A customer's request to purchase one or more items      | Purchase, transaction |
+| **Invoice** | A request for payment sent to a customer after delivery | Bill, payment request |
+
+## People
+
+| Term         | Definition                                  | Aliases to avoid       |
+| ------------ | ------------------------------------------- | ---------------------- |
+| **Customer** | A person or organization that places orders | Client, buyer, account |
+| **User**     | An authentication identity in the system    | Login, account         |
+
+## Relationships
+
+- An **Invoice** belongs to exactly one **Customer**
+- An **Order** produces one or more **Invoices**
+
+## Example dialogue
+
+> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"
+> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed. A single **Order** can produce multiple **Invoices** if items ship in separate **Shipments**."
+> **Dev:** "So if a **Shipment** is cancelled before dispatch, no **Invoice** exists for it?"
+> **Domain expert:** "Exactly. The **Invoice** lifecycle is tied to the **Fulfillment**, not the **Order**."
+
+## Flagged ambiguities
+
+- "account" was used to mean both **Customer** and **User** — these are distinct concepts: a **Customer** places orders, while a **User** is an authentication identity that may or may not represent a **Customer**.
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
+- **Flag conflicts explicitly.** If a term is used ambiguously in the conversation, call it out in the "Flagged ambiguities" section with a clear recommendation.
+- **Only include terms relevant for domain experts.** Skip the names of modules or classes unless they have meaning in the domain language.
+- **Keep definitions tight.** One sentence max. Define what it IS, not what it does.
+- **Show relationships.** Use bold term names and express cardinality where obvious.
+- **Only include domain terms.** Skip generic programming concepts (array, function, endpoint) unless they have domain-specific meaning.
+- **Group terms into multiple tables** when natural clusters emerge (e.g. by subdomain, lifecycle, or actor). Each group gets its own heading and table. If all terms belong to a single cohesive domain, one table is fine — don't force groupings.
+- **Write an example dialogue.** A short conversation (3-5 exchanges) between a dev and a domain expert that demonstrates how the terms interact naturally. The dialogue should clarify boundaries between related concepts and show terms being used precisely.
+
+<example>
+
+## Example dialogue
+
+> **Dev:** "How do I test the **sync service** without Docker?"
+
+> **Domain expert:** "Provide the **filesystem layer** instead of the **Docker layer**. It implements the same **Sandbox service** interface but uses a local directory as the **sandbox**."
+
+> **Dev:** "So **sync-in** still creates a **bundle** and unpacks it?"
+
+> **Domain expert:** "Exactly. The **sync service** doesn't know which layer it's talking to. It calls `exec` and `copyIn` — the **filesystem layer** just runs those as local shell commands."
+
+</example>
+
+## Re-running
+
+When invoked again in the same conversation:
+
+1. Read the existing `UBIQUITOUS_LANGUAGE.md`
+2. Incorporate any new terms from subsequent discussion
+3. Update definitions if understanding has evolved
+4. Re-flag any new ambiguities
+5. Rewrite the example dialogue to incorporate new terms

package/skills/use-my-browser/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: use-my-browser
+description: Use when work depends on the user's live browser session or visible rendered state rather than static fetches, especially for browser debugging contexts or DevTools-selected elements or requests, logged-in dashboards or CMS flows, localhost apps, forms, uploads, downloads, media inspection, DOM or iframe inspection, Shadow DOM, or browser failures that look like soft 404s, auth walls, anti-bot checks, or rate limits.
+---
+
+Do not treat this skill as a generic browsing default. Route from the evidence you need, not from tool preference.
+
+Every task must be classified before you choose a route:
+
+- `static-capable`: the evidence can be produced without live browser state, visible confirmation, or page interaction
+- `browser-required`: the evidence depends on rendered state, interaction, live session behavior, or browser-only structures
+
+Only `static-capable` tasks may fall back to static retrieval, `curl`, or other non-browser paths. Once a task is `browser-required`, stay on the browser path and mark missing capability as `blocked` instead of silently downgrading.
+
+## Prerequisite check
+
+This skill is for work inside the user's live browser session, not for launching a separate fresh automation browser.
+
+Before doing browser automation, confirm that your environment already has access to a live browser stack that can provide the capabilities the task depends on, such as page inventory, task-owned page creation, page selection, snapshots or visible-state reads, DOM inspection, text or form input, uploads, dialogs, console inspection, and network inspection. The exact stack does not matter here: confirm capability, not brand.
+
+If the live browser stack is unavailable, do not attempt browser automation through this skill. Only `static-capable` work may fall back to static retrieval.
+
+Live browser automation can trigger anti-bot or anti-automation defenses on some sites. Use browser interaction only when the task truly needs it, and avoid unnecessary repetitive actions once the needed evidence has been obtained.
+
+## Experience loop
+
+Treat site patterns as part of the browser protocol, not as optional background reading.
+
+For `browser-required` work, run this loop:
+
+1. As soon as the target domain is known, check whether a matching note already exists under [`references/site-patterns/`](./references/site-patterns/).
+2. If a note exists, read it before the first meaningful browser mutation on that domain.
+3. During the run, watch for verified site-specific facts that would change how a future run should operate.
+4. Before you consider the task complete, decide whether the run produced a reusable fact, disproved an existing fact, or produced no reusable site-specific learning.
+5. If the run verified something reusable or disproved an existing claim, update the matching note before finishing.
+
+Do not create a domain note for one-off noise. Do not skip the end-of-run review just because the task itself succeeded.
+
+Writeback is expected when a run verifies any of the following:
+
+- a stable route shape or required query parameter
+- a login, session inheritance, or `isolatedContext` quirk
+- a reliable interaction primitive such as hover, keyboard entry, upload sequencing, or a selector bridge pattern
+- a domain where DOM-generated links are reliable but hand-built URLs are not
+- predictable anti-automation friction or a misleading platform error state
+- a reusable media extraction or iframe / Shadow DOM access pattern
+
+## Decision guide
+
+Start with the outcome, not the tool. Make the user's goal explicit, define what counts as done, and choose the cheapest route that can still produce the right evidence.
+
+Use this routing order:
+
+1. Decide whether the task is `static-capable` or `browser-required`.
+2. If the task is `static-capable`, load [`references/task-routing.md`](./references/task-routing.md) and stay on the cheapest route that still satisfies the evidence target.
+3. If the task is `browser-required`, load [`references/browser-playbook.md`](./references/browser-playbook.md).
+4. If browser-required capability is uncertain in a fresh host session, also load [`references/browser-capability-matrix.md`](./references/browser-capability-matrix.md).
+5. If the user already has an active browser debugging context, such as a selected inspector element or network request, also load [`references/debug-handoff.md`](./references/debug-handoff.md).
+6. If the browser-required task touches a logged-in dashboard, admin surface, CMS, editor, or any save / publish / update flow, also load [`references/control-plane-workflows.md`](./references/control-plane-workflows.md).
+7. If the current failure shape suggests a soft 404, content-unavailable state, suspicious no-op interaction, auth wall, rate limit, or anti-automation defense, also load [`references/anti-automation-friction.md`](./references/anti-automation-friction.md).
+8. If the browser-required task includes iframe, Shadow DOM, collapsed content, or lazy-loaded evidence, also load [`references/deep-dom.md`](./references/deep-dom.md).
+9. If the important evidence lives in an image, audio clip, or video, also load [`references/media-inspection.md`](./references/media-inspection.md).
+10. If browser work can be divided across independent page owners or sub-agents, also load [`references/parallel-browser-ownership.md`](./references/parallel-browser-ownership.md).
+11. If you already know a reliable selector but need an MCP-native `uid` target, also load [`references/selector-bridge.md`](./references/selector-bridge.md).
+12. If page actions leave state ambiguous, a page unexpectedly navigates, an old `uid` may have gone stale, or console / network inspection is now needed to explain the next browser decision, also load [`references/browser-recovery.md`](./references/browser-recovery.md).
+13. If the target site already has a matching domain note under [`references/site-patterns/`](./references/site-patterns/), read that note before operating on the site.
+
+Treat the following as `browser-required` by default:
+
+- `localhost`, `127.0.0.1`, or benchmark-style local fixtures
+- uploads, downloads, drag-and-drop, hover, keyboard-native entry, or visible confirmation states
+- same-origin iframe inspection, Shadow DOM inspection, `details` / collapsed evidence, or lazy-loaded content
+- any task where "what the page visibly shows" is itself the evidence
+
+The normal happy path for a common task is this entrypoint plus one or two references, not the entire reference set.
+
+## Hard rules
+
+- Use browser interaction only when live browser state is part of the evidence or required action.
+- Once a task is `browser-required`, do not silently downgrade.
+- Treat this file as the entrypoint and each reference file as a single-purpose authority. Do not duplicate rules across files.
+- Keep reference loading one level deep. Decide the next file from this entrypoint instead of turning one reference into a hub that links to more references.
+- Do not ask the user to log in just because a page looks restricted. First confirm whether the target content or action is actually blocked.
+- Prefer site-generated DOM links over hand-built URLs once the page has shown you the path it expects.
+- Prefer MCP-native actions over script-driven interaction when the task is genuinely an in-browser action.
+- Only close pages you created.
+- Prefer primary sources over aggregators or repeated secondary reporting.
+- If a matching site pattern note exists, read it before the first meaningful browser mutation on that domain.
+- Do not finish a `browser-required` task without explicitly checking whether the run should create, update, downgrade, or remove a site-pattern claim.
+- If an existing site-pattern claim fails under comparable conditions, stop trusting it, fall back to the generic workflow, and update the note instead of retrying the stale assumption.
+- Do not use `curl`, `Invoke-WebRequest`, or shell HTTP fetches for `browser-required` tasks.
+- Do not treat a generic page-opening tool as evidence that localhost deep interaction is available.
+- Do not switch routes just because a browser capability probe failed. Record the missing capability and stop.
+- When the user indicates an active browser debugging context, prefer handoff from that current context over fresh reproduction from scratch.
+
+## Reference index
+
+- [`references/task-routing.md`](./references/task-routing.md): static retrieval vs live browser routing
+- [`references/browser-playbook.md`](./references/browser-playbook.md): core page-action protocol and base browser loop
+- [`references/browser-capability-matrix.md`](./references/browser-capability-matrix.md): capability proof for uncertain host sessions
+- [`references/debug-handoff.md`](./references/debug-handoff.md): active debugging-context handoff
+- [`references/control-plane-workflows.md`](./references/control-plane-workflows.md): logged-in dashboard / CMS save-publish discipline
+- [`references/anti-automation-friction.md`](./references/anti-automation-friction.md): soft 404 / auth / anti-automation classification
+- [`references/deep-dom.md`](./references/deep-dom.md): iframe, Shadow DOM, collapsed, or lazy-loaded evidence
+- [`references/media-inspection.md`](./references/media-inspection.md): image, audio, and video evidence
+- [`references/parallel-browser-ownership.md`](./references/parallel-browser-ownership.md): multi-owner browser coordination
+- [`references/selector-bridge.md`](./references/selector-bridge.md): selector-to-`uid` bridging
+- [`references/browser-recovery.md`](./references/browser-recovery.md): stale `uid`, navigation drift, and console / network escalation
+- [`references/site-patterns/README.md`](./references/site-patterns/README.md): site-pattern note maintenance rules
+- [site-patterns/{domain}.md](./references/site-patterns/): existing domain-specific operating knowledge

package/skills/using-superpowers/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: using-superpowers
+description: Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions
+---
+
+<SUBAGENT-STOP>
+If you were dispatched as a subagent to execute a specific task, skip this skill.
+</SUBAGENT-STOP>
+
+<EXTREMELY-IMPORTANT>
+If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.
+
+IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
+
+This is not negotiable. This is not optional. You cannot rationalize your way out of this.
+</EXTREMELY-IMPORTANT>
+
+## Instruction Priority
+
+Superpowers skills override default system prompt behavior, but **user instructions always take precedence**:
+
+1. **User's explicit instructions** (CLAUDE.md, GEMINI.md, AGENTS.md, direct requests) — highest priority
+2. **Superpowers skills** — override default system behavior where they conflict
+3. **Default system prompt** — lowest priority
+
+If CLAUDE.md, GEMINI.md, or AGENTS.md says "don't use TDD" and a skill says "always use TDD," follow the user's instructions. The user is in control.
+
+## How to Access Skills
+
+**Never read skill files manually with file tools** — always use your platform's skill-loading mechanism so the skill is properly activated.
+
+**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you — follow it directly.
+
+**In Codex:** Skills load natively. Follow the instructions presented when a skill activates.
+
+**In Copilot CLI:** Use the `skill` tool. Skills are auto-discovered from installed plugins.
+
+**In Gemini CLI:** Skills activate via the `activate_skill` tool. Gemini loads skill metadata at session start and activates the full content on demand.
+
+**In other environments:** Check your platform's documentation for how skills are loaded.
+
+## Platform Adaptation
+
+Skills speak in actions ("dispatch a subagent", "create a todo", "read a file") rather than naming any one runtime's tools. For per-platform tool equivalents and instructions-file conventions, see [claude-code-tools.md](references/claude-code-tools.md), [codex-tools.md](references/codex-tools.md), [copilot-tools.md](references/copilot-tools.md), [gemini-tools.md](references/gemini-tools.md), [pi-tools.md](references/pi-tools.md), and [antigravity-tools.md](references/antigravity-tools.md). Gemini CLI users get the tool mapping loaded automatically via GEMINI.md.
+
+# Using Skills
+
+## The Rule
+
+**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it.
+
+```dot
+digraph skill_flow {
+    "User message received" [shape=doublecircle];
+    "About to enter plan mode?" [shape=doublecircle];
+    "Already brainstormed?" [shape=diamond];
+    "Invoke brainstorming skill" [shape=box];
+    "Might any skill apply?" [shape=diamond];
+    "Invoke the skill" [shape=box];
+    "Announce: 'Using [skill] to [purpose]'" [shape=box];
+    "Has checklist?" [shape=diamond];
+    "Create a todo per item" [shape=box];
+    "Follow skill exactly" [shape=box];
+    "Respond (including clarifications)" [shape=doublecircle];
+
+    "About to enter plan mode?" -> "Already brainstormed?";
+    "Already brainstormed?" -> "Invoke brainstorming skill" [label="no"];
+    "Already brainstormed?" -> "Might any skill apply?" [label="yes"];
+    "Invoke brainstorming skill" -> "Might any skill apply?";
+
+    "User message received" -> "Might any skill apply?";
+    "Might any skill apply?" -> "Invoke the skill" [label="yes, even 1%"];
+    "Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
+    "Invoke the skill" -> "Announce: 'Using [skill] to [purpose]'";
+    "Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
+    "Has checklist?" -> "Create a todo per item" [label="yes"];
+    "Has checklist?" -> "Follow skill exactly" [label="no"];
+    "Create a todo per item" -> "Follow skill exactly";
+}
+```
+
+## Red Flags
+
+These thoughts mean STOP—you're rationalizing:
+
+| Thought | Reality |
+|---------|---------|
+| "This is just a simple question" | Questions are tasks. Check for skills. |
+| "I need more context first" | Skill check comes BEFORE clarifying questions. |
+| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
+| "I can check git/files quickly" | Files lack conversation context. Check for skills. |
+| "Let me gather information first" | Skills tell you HOW to gather information. |
+| "This doesn't need a formal skill" | If a skill exists, use it. |
+| "I remember this skill" | Skills evolve. Read current version. |
+| "This doesn't count as a task" | Action = task. Check for skills. |
+| "The skill is overkill" | Simple things become complex. Use it. |
+| "I'll just do this one thing first" | Check BEFORE doing anything. |
+| "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
+| "I know what that means" | Knowing the concept ≠ using the skill. Invoke it. |
+
+## Skill Priority
+
+When multiple skills could apply, use this order:
+
+1. **Process skills first** (brainstorming, systematic-debugging) - these determine HOW to approach the task
+2. **Implementation skills second** (frontend-design, mcp-builder) - these guide execution
+
+"Let's build X" → brainstorming first, then implementation skills.
+"Fix this bug" → systematic-debugging first, then domain-specific skills.
+
+## Skill Types
+
+**Rigid** (TDD, systematic-debugging): Follow exactly. Don't adapt away discipline.
+
+**Flexible** (patterns): Adapt principles to context.
+
+The skill itself tells you which.
+
+## User Instructions
+
+Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.

package/skills/vercel-cli-with-tokens/SKILL.md

@@ -0,0 +1,353 @@
+---
+name: vercel-cli-with-tokens
+description: Deploy and manage projects on Vercel using token-based authentication. Use when working with Vercel CLI using access tokens rather than interactive login — e.g. "deploy to vercel", "set up vercel", "add environment variables to vercel".
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+
+# Vercel CLI with Tokens
+
+Deploy and manage projects on Vercel using the CLI with token-based authentication, without relying on `vercel login`.
+
+## Step 1: Locate the Vercel Token
+
+Before running any Vercel CLI commands, identify where the token is coming from. Work through these scenarios in order:
+
+### A) `VERCEL_TOKEN` is already set in the environment
+
+```bash
+printenv VERCEL_TOKEN
+```
+
+If this returns a value, you're ready. Skip to Step 2.
+
+### B) Token is in a `.env` file under `VERCEL_TOKEN`
+
+```bash
+grep '^VERCEL_TOKEN=' .env 2>/dev/null
+```
+
+If found, export it:
+
+```bash
+export VERCEL_TOKEN=$(grep '^VERCEL_TOKEN=' .env | cut -d= -f2-)
+```
+
+### C) Token is in a `.env` file under a different name
+
+Look for any variable that looks like a Vercel token (Vercel tokens typically start with `vca_`):
+
+```bash
+grep -i 'vercel' .env 2>/dev/null
+```
+
+Inspect the output to identify which variable holds the token, then export it as `VERCEL_TOKEN`:
+
+```bash
+export VERCEL_TOKEN=$(grep '^<VARIABLE_NAME>=' .env | cut -d= -f2-)
+```
+
+### D) No token found — ask the user
+
+If none of the above yield a token, ask the user to provide one. They can create a Vercel access token at vercel.com/account/tokens.
+
+---
+
+**Important:** Once `VERCEL_TOKEN` is exported as an environment variable, the Vercel CLI reads it natively — **do not pass it as a `--token` flag**. Putting secrets in command-line arguments exposes them in shell history and process listings.
+
+```bash
+# Bad — token visible in shell history and process listings
+vercel deploy --token "vca_abc123"
+
+# Good — CLI reads VERCEL_TOKEN from the environment
+export VERCEL_TOKEN="vca_abc123"
+vercel deploy
+```
+
+## Step 2: Locate the Project and Team
+
+Similarly, check for the project ID and team scope. These let the CLI target the right project without needing `vercel link`.
+
+```bash
+# Check environment
+printenv VERCEL_PROJECT_ID
+printenv VERCEL_ORG_ID
+
+# Or check .env
+grep -i 'vercel' .env 2>/dev/null
+```
+
+**If you have a project URL** (e.g. `https://vercel.com/my-team/my-project`), extract the team slug:
+
+```bash
+# e.g. "my-team" from "https://vercel.com/my-team/my-project"
+echo "$PROJECT_URL" | sed 's|https://vercel.com/||' | cut -d/ -f1
+```
+
+**If you have both `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` in your environment**, export them — the CLI will use these automatically and skip any `.vercel/` directory:
+
+```bash
+export VERCEL_ORG_ID="<org-id>"
+export VERCEL_PROJECT_ID="<project-id>"
+```
+
+Note: `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` must be set together — setting only one causes an error.
+
+## CLI Setup
+
+Ensure the Vercel CLI is installed and up to date:
+
+```bash
+npm install -g vercel
+vercel --version
+```
+
+## Deploying a Project
+
+Always deploy as **preview** unless the user explicitly requests production. Choose a method based on what you have available.
+
+### Quick Deploy (have project ID — no linking needed)
+
+When `VERCEL_TOKEN` and `VERCEL_PROJECT_ID` are set in the environment, deploy directly:
+
+```bash
+vercel deploy -y --no-wait
+```
+
+With a team scope (either via `VERCEL_ORG_ID` or `--scope`):
+
+```bash
+vercel deploy --scope <team-slug> -y --no-wait
+```
+
+Production (only when explicitly requested):
+
+```bash
+vercel deploy --prod --scope <team-slug> -y --no-wait
+```
+
+Check status:
+
+```bash
+vercel inspect <deployment-url>
+```
+
+### Full Deploy Flow (no project ID — need to link)
+
+Use this when you have a token and team but no pre-existing project ID.
+
+#### Check project state first
+
+```bash
+# Does the project have a git remote?
+git remote get-url origin 2>/dev/null
+
+# Is it already linked to a Vercel project?
+cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
+```
+
+#### Link the project
+
+**With git remote (preferred):**
+
+```bash
+vercel link --repo --scope <team-slug> -y
+```
+
+Reads the git remote and connects to the matching Vercel project. Creates `.vercel/repo.json`. More reliable than plain `vercel link`, which matches by directory name.
+
+**Without git remote:**
+
+```bash
+vercel link --scope <team-slug> -y
+```
+
+Creates `.vercel/project.json`.
+
+**Link to a specific project by name:**
+
+```bash
+vercel link --project <project-name> --scope <team-slug> -y
+```
+
+If the project is already linked, check `orgId` in `.vercel/project.json` or `.vercel/repo.json` to verify it matches the intended team.
+
+#### Deploy after linking
+
+**A) Git Push Deploy — has git remote (preferred)**
+
+Git pushes trigger automatic Vercel deployments.
+
+1. **Ask the user before pushing.** Never push without explicit approval.
+2. Commit and push:
+   ```bash
+   git add .
+   git commit -m "deploy: <description of changes>"
+   git push
+   ```
+3. Vercel builds automatically. Non-production branches get preview deployments.
+4. Retrieve the deployment URL:
+   ```bash
+   sleep 5
+   vercel ls --format json --scope <team-slug>
+   ```
+   Find the latest entry in the `deployments` array.
+
+**B) CLI Deploy — no git remote**
+
+```bash
+vercel deploy --scope <team-slug> -y --no-wait
+```
+
+Check status:
+
+```bash
+vercel inspect <deployment-url>
+```
+
+### Deploying from a Remote Repository (code not cloned locally)
+
+1. Clone the repository:
+   ```bash
+   git clone <repo-url>
+   cd <repo-name>
+   ```
+2. Link to Vercel:
+   ```bash
+   vercel link --repo --scope <team-slug> -y
+   ```
+3. Deploy via git push (if you have push access) or CLI deploy.
+
+### About `.vercel/` Directory
+
+A linked project has either:
+- `.vercel/project.json` — from `vercel link`. Contains `projectId` and `orgId`.
+- `.vercel/repo.json` — from `vercel link --repo`. Contains `orgId`, `remoteName`, and a `projects` map.
+
+Not needed when `VERCEL_ORG_ID` + `VERCEL_PROJECT_ID` are both set in the environment.
+
+**Do NOT** run `vercel project inspect` or `vercel link` in an unlinked directory to detect state — they will interactively prompt or silently link as a side-effect. `vercel ls` is safe (in an unlinked directory it defaults to showing all deployments for the scope). `vercel whoami` is safe anywhere.
+
+## Managing Environment Variables
+
+```bash
+# Set for all environments
+echo "value" | vercel env add VAR_NAME --scope <team-slug>
+
+# Set for a specific environment (production, preview, development)
+echo "value" | vercel env add VAR_NAME production --scope <team-slug>
+
+# List environment variables
+vercel env ls --scope <team-slug>
+
+# Pull env vars to local .env.local file
+vercel env pull --scope <team-slug>
+
+# Remove a variable
+vercel env rm VAR_NAME --scope <team-slug> -y
+```
+
+## Inspecting Deployments
+
+```bash
+# List recent deployments
+vercel ls --format json --scope <team-slug>
+
+# Inspect a specific deployment
+vercel inspect <deployment-url>
+
+# View build logs (requires Vercel CLI v35+)
+vercel inspect <deployment-url> --logs
+
+# View runtime request logs (follows live by default; add --no-follow for a one-shot snapshot)
+vercel logs <deployment-url>
+```
+
+## Managing Domains
+
+```bash
+# List domains
+vercel domains ls --scope <team-slug>
+
+# Add a domain to the project — linked or env-linked directory (1 arg)
+vercel domains add <domain> --scope <team-slug>
+
+# Add a domain — unlinked directory (requires <project> positional)
+vercel domains add <domain> <project> --scope <team-slug>
+```
+
+## Stripe Projects Plan Changes
+
+If this project is managed by Stripe Projects. **Ask the user before running any paid or destructive plan change** — upgrades bill a real card, downgrades remove seats.
+
+First run `stripe projects status --json` to confirm the Vercel resource's local name. The examples below assume the default (`vercel-plan`); substitute the actual name if it was renamed at `stripe projects add` time.
+
+- **Upgrade to Pro:** `stripe projects add vercel/pro` (or `stripe projects upgrade vercel-plan pro`)
+- **Downgrade to Hobby:** `stripe projects downgrade vercel-plan hobby`
+
+### What Pro gives you
+
+- $20/month platform fee, includes $20/month of usage credit.
+- Turbo build machines (30 vCPUs, 60 GB memory) by default for new projects — significantly faster builds than Hobby.
+- 1 deploying seat + unlimited free Viewer seats (read-only collaborators, preview comments).
+- Higher included allocations (1 TB Fast Data Transfer, 10M Edge Requests per month).
+- Paid add-ons available: SAML SSO, HIPAA BAA, Flags Explorer, Observability Plus, Speed Insights, Web Analytics Plus.
+
+Full details: https://vercel.com/docs/plans/pro-plan
+
+## Working Agreement
+
+- **Never pass `VERCEL_TOKEN` as a `--token` flag.** Export it as an environment variable and let the CLI read it natively.
+- **Check the environment for tokens before asking the user.** Look in the current env and `.env` files first.
+- **Default to preview deployments.** Only deploy to production when explicitly asked.
+- **Ask before pushing to git.** Never push commits without the user's approval.
+- **Do not modify `.vercel/` files directly.** The CLI manages this directory. Reading them (e.g. to verify `orgId`) is fine.
+- **Do not curl/fetch deployed URLs to verify.** Just return the link to the user.
+- **Use `--format json`** when structured output will help with follow-up steps.
+- **Use `-y`** on commands that prompt for confirmation to avoid interactive blocking.
+
+## Troubleshooting
+
+### Token not found
+
+Check the environment and any `.env` files present:
+
+```bash
+printenv | grep -i vercel
+grep -i vercel .env 2>/dev/null
+```
+
+### Authentication error
+
+If the CLI fails with `Authentication required`:
+- The token may be expired or invalid.
+- Verify: `vercel whoami` (uses `VERCEL_TOKEN` from environment).
+- Ask the user for a fresh token.
+
+### Wrong team
+
+Verify the scope is correct:
+
+```bash
+vercel whoami --scope <team-slug>
+```
+
+### Build failure
+
+Check the build logs:
+
+```bash
+vercel inspect <deployment-url> --logs
+```
+
+Common causes:
+- Missing dependencies — ensure `package.json` is complete and committed.
+- Missing environment variables — add with `vercel env add`.
+- Framework misconfiguration — check `vercel.json`. Vercel auto-detects frameworks (Next.js, Remix, Vite, etc.) from `package.json`; override with `vercel.json` if detection is wrong.
+
+### CLI not installed
+
+```bash
+npm install -g vercel
+```