@glbgpt/cli 0.1.0-test.5 → 0.1.1

package/skills/globalgpt-image/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: globalgpt-image
+description: >
+  Generates and edits images through the user's GlobalGPT account via the glbgpt CLI.
+  Use when the user wants to create, generate, edit, restyle, or touch up an image,
+  picture, photo, logo, illustration, poster, thumbnail, banner, or icon — including
+  image-to-image edits that build on a reference image. NOT for video, animation, or
+  animating a still image — use globalgpt-video for those. NOT for delegating code
+  work to a GlobalGPT model — that is globalgpt-coding, which the user invokes
+  explicitly.
+---
+
+# GlobalGPT image generation
+
+Generate images through the user's GlobalGPT account with the `glbgpt` CLI.
+
+<!-- shared:banner -->
+> **Generation spends real credits.** Price a job without running it using
+> `--estimate`; show the balance with `glbgpt account`.
+<!-- /shared:banner -->
+
+## Before the first call
+
+<!-- shared:setup -->
+Run `glbgpt whoami`. If the command is not found, tell the user to install it with
+`npm i -g @glbgpt/cli`. If it reports that nobody is signed in, ask the user to
+run `glbgpt login` themselves — it opens a browser. Never try to authenticate for
+them.
+<!-- /shared:setup -->
+
+## Quick start
+
+```bash
+glbgpt image "a red fox in falling snow, cinematic lighting"   # blocks until saved
+glbgpt image "a red fox in snow" --estimate                    # price only, generates nothing
+```
+
+The first line prints the saved path once it finishes. Files land in
+`./glbgpt-output/` unless `-o <dir>` says otherwise.
+
+## When invoked directly
+
+If the user ran /globalgpt-image without saying what to make, run
+`glbgpt model list image` and show the models as a menu — use your host's native option picker if it has one, else a numbered list — adding:
+"pick one, or just tell me what to make and I'll use the default." Generate with
+`-m <model>` when they pick. When this skill triggers from ordinary conversation
+instead, skip the menu: use the default model and only ask something when the
+subject itself is unclear.
+
+## Before you spend
+
+A generation you have to redo costs the full price again, so know what to generate
+before you run the command — without interrogating the user:
+
+- **Subject unclear or missing** ("make me an image"): ask what it should show — one
+  short question, not a menu of options.
+- **Two plausible readings**: say how you read it and confirm before generating.
+  A word that does not parse cleanly, a likely typo, or anything you had to
+  reinterpret to make sense of COUNTS as two readings — even if one reading feels
+  obvious to you. Guessing and offering to redo doubles the cost of being wrong.
+- **Subject clear**: go. Style, aspect ratio and model all have sensible defaults —
+  do not ask about them unless the user seems to care.
+- Never ask more than one question per turn.
+
+## Choosing a model
+
+Run `glbgpt model list image` and choose from what it prints. `glbgpt model show
+<model>` gives one model's parameters and limits, including which aspect ratios and
+resolutions it accepts.
+
+The catalog is served from the account and changes over time, so treat a model name
+you remember as a guess: list first. Omit `-m/--model` entirely unless the user asked
+for a specific model — the default is chosen for general use.
+
+## Footguns
+
+These are the mistakes that cost money or silently produce the wrong thing.
+
+- **Reference images belong in a flag, never in the prompt.** Use `-i ./ref.png` for
+  image-to-image. A path or URL written into the prompt text reaches the media model
+  as literal words; it cannot fetch anything.
+- **Do not describe a result you have not seen.** Never tell the user what the image
+  looks like, its resolution, or any detail you have not verified in the file itself.
+  Most settings came from the model's own defaults, not from you.
+- **Do not build a polling loop.** `glbgpt image` generation blocks until the file is
+  saved. Reach for `--detach` only when you deliberately want several generations
+  running at once, then collect them with `glbgpt task wait <id>` and
+  `glbgpt task download <id>`.
+- **Never retry a failed generation automatically.** A genuine failure is not charged,
+  but a generation that timed out or was interrupted may still be running on the server
+  and will be charged — retrying pays twice for the same thing. Report the failure and
+  let the user decide.
+- **Ask before batches.** More than two or three generations is real money. Confirm
+  the plan with the user first.
+- **Set only the parameters the user asked for.** Every flag you leave out falls back
+  to a default tuned for that model; invented values make results worse and can cost
+  more.
+
+## Common jobs
+
+Ready-made command lines for thumbnails, product shots, and image edits:
+[references/recipes.md](references/recipes.md).
+
+## When something fails
+
+Read the error text — the CLI says what went wrong (not signed in, not enough
+credits, a parameter the chosen model does not support). Fix the cause or report it
+to the user; never retry blindly. Common failures and what they mean:
+[references/troubleshooting.md](references/troubleshooting.md).

package/skills/globalgpt-image/references/recipes.md

@@ -0,0 +1,52 @@
+# Recipes
+
+Intent → command. Check `glbgpt model list image` for what is available before
+picking a model; these recipes deliberately leave `-m` off so the default applies.
+
+## Images
+
+**Square social image**
+```bash
+glbgpt image "<subject>, <style>" --ar 1:1
+```
+
+**Wide thumbnail or cover**
+```bash
+glbgpt image "<subject>, bold composition, high contrast" --ar 16:9
+```
+
+**Product shot on a clean background**
+```bash
+glbgpt image "<product>, studio lighting, plain white background, product photography" --ar 1:1 --res 2K
+```
+
+**Edit or restyle an existing image**
+```bash
+glbgpt image "<what to change>" -i ./original.png
+```
+
+**Avoid something specific**
+```bash
+glbgpt image "<subject>" --negative-prompt "text, watermark, extra fingers"
+```
+
+**Reproducible output** — reuse a seed the user gives you:
+```bash
+glbgpt image "<subject>" --seed 12345
+```
+
+## Pricing a job first
+
+```bash
+glbgpt image "<subject>" --estimate     # prints the price, generates nothing
+```
+
+## Several at once
+
+Only when the user has agreed to the batch:
+```bash
+glbgpt image "<a>" --detach           # prints a task id immediately
+glbgpt image "<b>" --detach
+glbgpt task list                      # ids and status
+glbgpt task download <id>             # fetch a finished result
+```

package/skills/globalgpt-image/references/troubleshooting.md

@@ -0,0 +1,49 @@
+# Troubleshooting
+
+<!-- shared:troubleshooting-common -->
+<!-- shared:login -->
+## "Not signed in"
+
+The user must run `glbgpt login` themselves — it opens a browser. On a headless box
+or over SSH, `glbgpt login --code` prints a URL instead: the user opens it on any
+machine with a browser, authorizes there, and pastes the code the page shows back
+into the terminal. Do not
+attempt to authenticate for them.
+<!-- /shared:login -->
+
+## Not enough credits, or a plan restriction
+
+The command reports a payment problem instead of generating. Show the user
+`glbgpt account` (balance and membership) and stop — do not retry, and do not try a
+different model hoping it is cheaper unless the user asks.
+
+## "Unknown model"
+
+The catalog is server-driven and the name you used no longer exists (or never did).
+Run `glbgpt model list image` or `glbgpt model list video` and use a name it prints.
+
+## A parameter is rejected
+
+Support differs per model — aspect ratios, resolutions, durations, audio and
+reference-image behaviour are all per-model. Run `glbgpt model show <model>` and use a
+value it lists, or drop the flag entirely so the model's default applies.
+
+## The generation failed after submitting
+
+A genuine failure is not charged — the CLI says so when it reports one. Report the
+failure and its reason to the user and let them decide what to do; never retry
+automatically, because a task that timed out or was interrupted may still be running
+and would then be charged again. `glbgpt task show <id>` gives the status and reason
+for a specific task, and `glbgpt task list` shows recent ones.
+
+## The command seems to hang
+
+Video generation takes minutes and the command blocks on purpose. Wait for it. If the
+process was interrupted, the task keeps running on the server: `glbgpt task list`
+finds it, `glbgpt task download <id>` fetches the result once it is ready.
+
+## The file is not where you expected
+
+Results are saved under `./glbgpt-output/` relative to the working directory unless
+`-o <dir>` was passed. The command prints the absolute path when it finishes.
+<!-- /shared:troubleshooting-common -->

package/skills/globalgpt-video/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: globalgpt-video
+description: >
+  Generates videos through the user's GlobalGPT account via the glbgpt CLI.
+  Use when the user wants to create or generate a video, clip, animation, or b-roll —
+  including animating a still image (image-to-video), turning a photo into motion,
+  and first/last-frame interpolation. NOT for still images — use globalgpt-image.
+  NOT for delegating code work to a GlobalGPT model — that is globalgpt-coding,
+  which the user invokes explicitly.
+---
+
+# GlobalGPT video generation
+
+Generate video through the user's GlobalGPT account with the `glbgpt` CLI.
+
+<!-- shared:banner -->
+> **Generation spends real credits.** Price a job without running it using
+> `--estimate`; show the balance with `glbgpt account`.
+<!-- /shared:banner -->
+
+## Before the first call
+
+<!-- shared:setup -->
+Run `glbgpt whoami`. If the command is not found, tell the user to install it with
+`npm i -g @glbgpt/cli`. If it reports that nobody is signed in, ask the user to
+run `glbgpt login` themselves — it opens a browser. Never try to authenticate for
+them.
+<!-- /shared:setup -->
+
+## Quick start
+
+```bash
+glbgpt video "slow waves on a beach at sunset" --ar 16:9   # minutes; blocks until saved
+glbgpt video "slow waves on a beach at sunset" --estimate  # price only, generates nothing
+```
+
+The first line prints the saved path once it finishes. Files land in
+`./glbgpt-output/` unless `-o <dir>` says otherwise.
+
+## When invoked directly
+
+If the user ran /globalgpt-video without saying what to make, run
+`glbgpt model list video` and show the models as a menu — use your host's native option picker if it has one, else a numbered list — adding:
+"pick one, or just tell me what to make and I'll use the default." Generate with
+`-m <model>` when they pick. When this skill triggers from ordinary conversation
+instead, skip the menu: use the default model and only ask something when the
+subject itself is unclear.
+
+## Before you spend
+
+A generation you have to redo costs the full price again, so know what to generate
+before you run the command — without interrogating the user:
+
+- **Subject unclear or missing** ("make me a video"): ask what it should show — one
+  short question, not a menu of options.
+- **Two plausible readings**: say how you read it and confirm before generating.
+  A word that does not parse cleanly, a likely typo, or anything you had to
+  reinterpret to make sense of COUNTS as two readings — even if one reading feels
+  obvious to you. Guessing and offering to redo doubles the cost of being wrong.
+- **Subject clear**: go. Style, aspect ratio and model all have sensible defaults —
+  do not ask about them unless the user seems to care.
+- Never ask more than one question per turn.
+
+## Choosing a model
+
+Run `glbgpt model list video` and choose from what it prints. `glbgpt model show
+<model>` gives one model's parameters and limits, including which aspect ratios,
+resolutions and durations it accepts.
+
+The catalog is served from the account and changes over time, so treat a model name
+you remember as a guess: list first. Omit `-m/--model` entirely unless the user asked
+for a specific model — the default is chosen for general use.
+
+## Footguns
+
+These are the mistakes that cost money or silently produce the wrong thing.
+
+- **Reference frames belong in a flag, never in the prompt.** Use `--start-image
+  ./frame.png` and `--end-image ./last.png` for image-to-video and first/last-frame
+  video. A path or URL written into the prompt text reaches the media model as
+  literal words; it cannot fetch anything.
+- **Do not describe a result you have not seen.** Never tell the user whether the
+  video has sound, what its resolution is, or how it looks. Most settings came from
+  the model's own defaults, not from you.
+- **Do not build a polling loop.** Video generation takes minutes and `glbgpt video`
+  blocks on purpose until the file is saved. Reach for `--detach` only when you
+  deliberately want several generations running at once, then collect them with
+  `glbgpt task wait <id>` and `glbgpt task download <id>`.
+- **Never retry a failed generation automatically.** A genuine failure is not charged,
+  but a generation that timed out or was interrupted may still be running on the server
+  and will be charged — retrying pays twice for the same thing. Report the failure and
+  let the user decide.
+- **Ask before batches.** More than two or three generations — especially videos — is
+  real money. Confirm the plan with the user first.
+- **Set only the parameters the user asked for.** Every flag you leave out falls back
+  to a default tuned for that model; invented values make results worse and can cost
+  more.
+
+## Common jobs
+
+Ready-made command lines for still-to-video and first/last-frame video:
+[references/recipes.md](references/recipes.md).
+
+## When something fails
+
+Read the error text — the CLI says what went wrong (not signed in, not enough
+credits, a parameter the chosen model does not support). Fix the cause or report it
+to the user; never retry blindly. Common failures and what they mean:
+[references/troubleshooting.md](references/troubleshooting.md).

package/skills/globalgpt-video/references/recipes.md

@@ -0,0 +1,50 @@
+# Recipes
+
+Intent → command. Check `glbgpt model list video` for what is available before
+picking a model; these recipes deliberately leave `-m` off so the default applies.
+
+## Video
+
+**Text to video**
+```bash
+glbgpt video "<scene>, slow camera move" --ar 16:9
+```
+
+**Vertical clip for social**
+```bash
+glbgpt video "<scene>" --ar 9:16
+```
+
+**Animate a still image**
+```bash
+glbgpt video "<how it should move>" --start-image ./frame.png
+```
+
+**Interpolate between two frames**
+```bash
+glbgpt video "<transition>" --start-image ./first.png --end-image ./last.png
+```
+
+**Length** — only when the user asks:
+```bash
+glbgpt video "<scene>" --duration 8
+```
+
+**Sound** — only on a model whose `glbgpt model show <model>` lists audio support; add
+`--audio` (or `--no-audio`) together with `-m <that-model>`.
+
+## Pricing a job first
+
+```bash
+glbgpt video "<scene>" --estimate     # prints the price, generates nothing
+```
+
+## Several at once
+
+Only when the user has agreed to the batch:
+```bash
+glbgpt video "<a>" --detach           # prints a task id immediately
+glbgpt video "<b>" --detach
+glbgpt task list                      # ids and status
+glbgpt task download <id>             # fetch a finished result
+```

package/skills/globalgpt-video/references/troubleshooting.md

@@ -0,0 +1,49 @@
+# Troubleshooting
+
+<!-- shared:troubleshooting-common -->
+<!-- shared:login -->
+## "Not signed in"
+
+The user must run `glbgpt login` themselves — it opens a browser. On a headless box
+or over SSH, `glbgpt login --code` prints a URL instead: the user opens it on any
+machine with a browser, authorizes there, and pastes the code the page shows back
+into the terminal. Do not
+attempt to authenticate for them.
+<!-- /shared:login -->
+
+## Not enough credits, or a plan restriction
+
+The command reports a payment problem instead of generating. Show the user
+`glbgpt account` (balance and membership) and stop — do not retry, and do not try a
+different model hoping it is cheaper unless the user asks.
+
+## "Unknown model"
+
+The catalog is server-driven and the name you used no longer exists (or never did).
+Run `glbgpt model list image` or `glbgpt model list video` and use a name it prints.
+
+## A parameter is rejected
+
+Support differs per model — aspect ratios, resolutions, durations, audio and
+reference-image behaviour are all per-model. Run `glbgpt model show <model>` and use a
+value it lists, or drop the flag entirely so the model's default applies.
+
+## The generation failed after submitting
+
+A genuine failure is not charged — the CLI says so when it reports one. Report the
+failure and its reason to the user and let them decide what to do; never retry
+automatically, because a task that timed out or was interrupted may still be running
+and would then be charged again. `glbgpt task show <id>` gives the status and reason
+for a specific task, and `glbgpt task list` shows recent ones.
+
+## The command seems to hang
+
+Video generation takes minutes and the command blocks on purpose. Wait for it. If the
+process was interrupted, the task keeps running on the server: `glbgpt task list`
+finds it, `glbgpt task download <id>` fetches the result once it is ready.
+
+## The file is not where you expected
+
+Results are saved under `./glbgpt-output/` relative to the working directory unless
+`-o <dir>` was passed. The command prints the absolute path when it finishes.
+<!-- /shared:troubleshooting-common -->