corethink 1.0.0__tar.gz → 1.0.2__tar.gz

{corethink-1.0.0 → corethink-1.0.2}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: corethink
-Version: 1.0.0
+Version: 1.0.2
 Summary: The CoreThink Workbench from your terminal: environments, training, endpoints and more.
 Author-email: CoreThink <support@corethink.ai>
 License-Expression: MIT
 Project-URL: Homepage, https://corethink.ai
-Project-URL: Documentation, https://workbench.corethink.ai/app/docs
+Project-URL: Documentation, https://corethink.ai/docs/workbench-cli
+Project-URL: Reference, https://corethink.ai/docs/workbench-cli-reference
 Project-URL: Console, https://workbench.corethink.ai
 Keywords: corethink,workbench,llm,agents,cli,training
 Classifier: Development Status :: 5 - Production/Stable
@@ -18,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development
 Requires-Python: >=3.10
@@ -33,12 +35,24 @@ small models, check them against the base model, release them and call them —
 scriptable.
 
 ```bash
-pip install corethink        # or: pipx install corethink / uv tool install corethink
+pipx install corethink       # or: uv tool install corethink
 corethink login              # opens your browser to approve this terminal
 corethink env list
 ```
 
-Python 3.10 or newer, on Linux, macOS and Windows.
+Python 3.10 or newer, on Linux, macOS and Windows. **Docs:** [guide](https://corethink.ai/docs/workbench-cli) ·
+[every command](https://corethink.ai/docs/workbench-cli-reference)
+
+## Install
+
+| Where | How |
+| --- | --- |
+| Your machine | `pipx install corethink` or `uv tool install corethink` |
+| A virtual environment, conda, Docker or CI | `pip install corethink` |
+| Upgrade | `pipx upgrade corethink`, `uv tool upgrade corethink` or `pip install -U corethink` |
+
+`error: externally-managed-environment` from pip means your system Python (recent Ubuntu, Debian, Fedora, Homebrew)
+does not take packages: use pipx or uv as above. On Ubuntu: `sudo apt install pipx && pipx ensurepath`.
 
 ## Quick start
 
@@ -90,8 +104,8 @@ Make a token once (`corethink token create github-actions`, or in the Workbench:
 as `CORETHINK_TOKEN`. No login or config file is needed then:
 
 ```yaml
-- run: pip install corethink
-- run: corethink train start payroll --limit 10 --yes --json > run.json
+- run: pipx install corethink
+- run: corethink train start payroll --limit 10 --yes --watch   # fails the step if the run fails
   env:
     CORETHINK_TOKEN: ${{ secrets.CORETHINK_TOKEN }}
 ```
@@ -117,4 +131,5 @@ Shell completion: `corethink --install-completion`.
 
 ## Help
 
-Docs: <https://workbench.corethink.ai/app/docs> · Support: support@corethink.ai
+Guide: <https://corethink.ai/docs/workbench-cli> · Every command: <https://corethink.ai/docs/workbench-cli-reference> ·
+Workbench docs: <https://workbench.corethink.ai/app/docs> · Support: support@corethink.ai

{corethink-1.0.0 → corethink-1.0.2}/README.md

@@ -5,12 +5,24 @@ small models, check them against the base model, release them and call them —
 scriptable.
 
 ```bash
-pip install corethink        # or: pipx install corethink / uv tool install corethink
+pipx install corethink       # or: uv tool install corethink
 corethink login              # opens your browser to approve this terminal
 corethink env list
 ```
 
-Python 3.10 or newer, on Linux, macOS and Windows.
+Python 3.10 or newer, on Linux, macOS and Windows. **Docs:** [guide](https://corethink.ai/docs/workbench-cli) ·
+[every command](https://corethink.ai/docs/workbench-cli-reference)
+
+## Install
+
+| Where | How |
+| --- | --- |
+| Your machine | `pipx install corethink` or `uv tool install corethink` |
+| A virtual environment, conda, Docker or CI | `pip install corethink` |
+| Upgrade | `pipx upgrade corethink`, `uv tool upgrade corethink` or `pip install -U corethink` |
+
+`error: externally-managed-environment` from pip means your system Python (recent Ubuntu, Debian, Fedora, Homebrew)
+does not take packages: use pipx or uv as above. On Ubuntu: `sudo apt install pipx && pipx ensurepath`.
 
 ## Quick start
 
@@ -62,8 +74,8 @@ Make a token once (`corethink token create github-actions`, or in the Workbench:
 as `CORETHINK_TOKEN`. No login or config file is needed then:
 
 ```yaml
-- run: pip install corethink
-- run: corethink train start payroll --limit 10 --yes --json > run.json
+- run: pipx install corethink
+- run: corethink train start payroll --limit 10 --yes --watch   # fails the step if the run fails
   env:
     CORETHINK_TOKEN: ${{ secrets.CORETHINK_TOKEN }}
 ```
@@ -89,4 +101,5 @@ Shell completion: `corethink --install-completion`.
 
 ## Help
 
-Docs: <https://workbench.corethink.ai/app/docs> · Support: support@corethink.ai
+Guide: <https://corethink.ai/docs/workbench-cli> · Every command: <https://corethink.ai/docs/workbench-cli-reference> ·
+Workbench docs: <https://workbench.corethink.ai/app/docs> · Support: support@corethink.ai

{corethink-1.0.0 → corethink-1.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "corethink"
-version = "1.0.0"
+version = "1.0.2"
 description = "The CoreThink Workbench from your terminal: environments, training, endpoints and more."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -22,6 +22,7 @@ classifiers = [
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
   "Topic :: Scientific/Engineering :: Artificial Intelligence",
   "Topic :: Software Development",
 ]
@@ -33,7 +34,8 @@ dependencies = [
 
 [project.urls]
 Homepage = "https://corethink.ai"
-Documentation = "https://workbench.corethink.ai/app/docs"
+Documentation = "https://corethink.ai/docs/workbench-cli"
+Reference = "https://corethink.ai/docs/workbench-cli-reference"
 Console = "https://workbench.corethink.ai"
 
 [project.scripts]

{corethink-1.0.0 → corethink-1.0.2}/src/corethink/_version.py

@@ -1,3 +1,3 @@
 """The version of the `corethink` package (read by the build and by `corethink --version`)."""
 
-__version__ = "1.0.0"
+__version__ = "1.0.2"

{corethink-1.0.0 → corethink-1.0.2}/src/corethink/commands/admin.py

@@ -19,9 +19,55 @@ from corethink.client import ApiError
 from corethink.commands.workspace import entry_amount, entry_type
 from corethink.context import client
 
-app = typer.Typer(help="Every account and run on this Workbench (super admins only).", no_args_is_help=True)
-settings_app = typer.Typer(help="Account limits for everyone: show them, or change them with `set`.")
-superadmins_app = typer.Typer(help="Who can use the admin commands and page.")
+HELP = """Every account and run on this Workbench (super admins only).
+
+These commands look across every account and workspace on the Workbench, not just your own. Only super
+admins can use them; anyone else is told they cannot. `corethink admin superadmins` shows who can and
+manages the list.
+
+A typical flow: `corethink admin overview` for the totals, `corethink admin accounts` to find someone,
+`corethink admin account` to see one account in full, then `corethink admin add-credit` to give it credit
+or `corethink admin limits` to change its own limits. `corethink admin settings` holds the limits for every
+account. `corethink admin runs` and `corethink admin logs` look into any workspace's runs, and
+`corethink admin waitlist` shows who asked to join.
+
+Adding credit and changing limits ask for confirmation unless `--yes` is given.
+
+Examples:
+  corethink admin overview
+  corethink admin accounts --search acme.com
+  corethink admin add-credit ana@acme.com 50 --note "Pilot credit"
+  corethink admin runs --status failed
+"""
+
+SETTINGS_HELP = """Account limits for everyone: show them, or change them with `set`.
+
+`corethink admin settings` alone shows each limit: its name and key, its value (marked `(default)` when it
+was never changed), the default, the allowed range and whether it can also be set for one account. The
+limits are the welcome credit a new account gets, how many welcome credits are given per day, how many runs
+can go at once in a personal and in a team workspace, and the smallest and largest spending limit of a run.
+
+Change them with `corethink admin settings set`; give one account its own values with
+`corethink admin limits`.
+
+Examples:
+  corethink admin settings
+  corethink admin settings set signupCreditUsd=10 maxRunningJobs=3
+"""
+
+SUPERADMINS_HELP = """Who can use the admin commands and page.
+
+`corethink admin superadmins` alone lists them, as `list` does. `add` makes someone a super admin and
+`remove` takes it away. The Workbench's team owners are always super admins and cannot be removed here.
+
+Examples:
+  corethink admin superadmins
+  corethink admin superadmins add ana@acme.com --notify
+"""
+
+app = typer.Typer(help=HELP, no_args_is_help=True)
+settings_app = typer.Typer(help=SETTINGS_HELP)
+superadmins_app = typer.Typer(help=SUPERADMINS_HELP)
 
 YES_OPTION = typer.Option(False, "--yes", "-y", help="Do not ask.")
 JOB_ID = re.compile(r"^[0-9a-f-]{36}$")
@@ -155,7 +201,20 @@ def _change_text(values: dict[str, Any], units: dict[str, Any]) -> str:
 
 @app.command("overview")
 def overview() -> None:
-    """Accounts, runs, spend and credit across the Workbench."""
+    """Show totals across the Workbench: accounts, runs, spend and credit.
+
+    Accounts: the total, how many confirmed their email, how many are new in the last 7 days, and sign-ups
+    per day. Runs: running, queued, finished in the last 7 days (succeeded and failed) and the total. Spend
+    and credit: spent on runs overall and in the last 7 days; credit given or bought (welcome credit, added
+    by admins, bought); and how much is used, left and held by running jobs. Test accounts and their runs
+    are not counted.
+
+    With `--json` it returns `accounts`, `runs`, `spend` and `credit`. Look at accounts with
+    `corethink admin accounts` and runs with `corethink admin runs`.
+
+    Examples:
+      corethink admin overview
+    """
     data = _call("GET", "/api/v1/admin/overview")
     accounts, runs = data.get("accounts") or {}, data.get("runs") or {}
     spend, credit = data.get("spend") or {}, data.get("credit") or {}
@@ -228,9 +287,18 @@ def accounts(
     search: str = typer.Option(None, "--search", "-s", help="Only accounts whose email contains this."),
     limit: int = typer.Option(100, "--limit", "-n", min=1, help="Show at most this many."),
 ) -> None:
-    """Every account, newest first.
+    """List every account on the Workbench, newest first.
 
-    Example: corethink admin accounts --search acme.com
+    Shows each account's email, when it was created, whether its email is confirmed, how many workspaces it
+    is in, its balance, what it spent, its number of runs and its ID. `--search` keeps accounts whose email
+    contains the text; `--limit` shows at most that many. Test accounts are hidden.
+
+    With `--json` it returns `accounts` (those shown), `total` and `hiddenTestAccounts`. See one in full
+    with `corethink admin account`.
+
+    Examples:
+      corethink admin accounts
+      corethink admin accounts --search acme.com
     """
     data = _call("GET", "/api/v1/admin/accounts")
     every = data.get("accounts") or []
@@ -273,7 +341,19 @@ def accounts(
 def account(
     who: str = typer.Argument(..., metavar="ACCOUNT", help="The account's email or ID (or the start of either)."),
 ) -> None:
-    """One account: its workspaces, credit, limits and runs."""
+    """Show one account: its workspaces, credit, limits and runs.
+
+    Find the account by its email or ID, or the start of either. Shows its email, ID, when it was created,
+    whether it is confirmed, its balance (and how much running jobs hold) and what it spent on runs. Then
+    its workspaces with its role in each, its limits (the value in use, its own value and the value for
+    everyone), its 20 newest credit entries and its 20 newest runs.
+
+    With `--json` it returns `account`, `workspaces`, `limits`, `ledger` and `runs`. Give it credit with
+    `corethink admin add-credit`, or change its limits with `corethink admin limits`.
+
+    Examples:
+      corethink admin account ana@acme.com
+    """
     found = _find_account(who)
     detail = _call("GET", f"/api/v1/admin/accounts/{found['uid']}")
     shown = detail.get("account") or found
@@ -368,7 +448,17 @@ def add_credit(
 ) -> None:
     """Add promotional credit to an account.
 
-    Example: corethink admin add-credit ana@acme.com 50 --note "Pilot credit"
+    Adds up to $1,000 to the account's balance, with a note that its credit history shows (`--note` is
+    required). Asks for confirmation unless `--yes` is given. Each credit has a unique key (`--key`, a new
+    one by default): sending the same request again with the same key adds nothing, so a retried script
+    cannot add the credit twice.
+
+    With `--json` it returns `uid`, `email`, `key`, the new `balanceUsd` and, when the key was already used,
+    `repeated`. Check the result with `corethink admin account`.
+
+    Examples:
+      corethink admin add-credit ana@acme.com 50 --note "Pilot credit"
+      corethink admin add-credit ana@acme.com 50 --note "Pilot credit" --key pilot-ana-2026 --yes
     """
     if not 0 < usd <= 1000:
         ui.error("Give an amount from $0.01 to $1,000.")
@@ -405,9 +495,18 @@ def limits(
     ),
     yes: bool = YES_OPTION,
 ) -> None:
-    """Show an account's own limits, or set them.
+    """Show or set one account's own limits.
+
+    Without KEY=VALUE pairs it shows the account's limits: each limit's name and key, the value in use, the
+    account's own value (if it has one) and the value for everyone. With pairs it sets the account's own
+    values; the value `default` removes its own value, so the value for everyone applies again. Keys may be
+    written in any case or with dashes. `corethink admin settings` shows which limits can be set per account.
+
+    Setting asks for confirmation unless `--yes` is given. With `--json` it returns the account's `limits`.
 
-    Example: corethink admin limits ana@acme.com maxRunningJobs=5 maxBudgetUsd=default
+    Examples:
+      corethink admin limits ana@acme.com
+      corethink admin limits ana@acme.com maxRunningJobs=5 maxBudgetUsd=default
     """
     found = _find_account(who)
     current = _call("GET", f"/api/v1/admin/accounts/{found['uid']}").get("limits") or {}
@@ -477,7 +576,16 @@ def settings_set(
 ) -> None:
     """Change limits for every account; limits left out stay as they are.
 
-    Example: corethink admin settings set signupCreditUsd=10 maxRunningJobs=3
+    Give KEY=VALUE pairs with the keys `corethink admin settings` shows, in any case or with dashes. The
+    value `default` goes back to the default. Each value must be in the allowed range that
+    `corethink admin settings` shows. An account with its own value for a limit keeps it.
+
+    Asks for confirmation unless `--yes` is given, then shows the limits as saved. With `--json` it returns
+    the saved settings, with `limits`.
+
+    Examples:
+      corethink admin settings set signupCreditUsd=10 maxRunningJobs=3
+      corethink admin settings set max-budget-usd=default --yes
     """
     current = _call("GET", "/api/v1/admin/settings")
     rows = current.get("limits") or []
@@ -511,9 +619,20 @@ def runs(
     ),
     limit: int = typer.Option(50, "--limit", "-n", min=1, help="Show at most this many."),
 ) -> None:
-    """Every workspace's runs, newest first.
+    """List every workspace's runs, newest first.
+
+    Shows each run's job ID, who started it, its workspace and environment, its kind, its status (running,
+    starting, queued, paused, succeeded, failed or cancelled), its stage, what it spent of its limit and when
+    it started. `--status` keeps `running`, `queued` (with paused), `succeeded` or `failed` (with cancelled)
+    runs. `--search` matches the person, workspace, environment or job ID. Test accounts' runs are hidden
+    unless `--qa` is given, and then marked QA.
 
-    Example: corethink admin runs --status failed
+    With `--json` it returns `runs` (those shown) and notes such as `hiddenTestRuns` and `capped`. Download
+    a run's logs with `corethink admin logs`.
+
+    Examples:
+      corethink admin runs --status failed
+      corethink admin runs --search acme.com --limit 20
     """
     if status is not None and status.lower() not in RUN_FILTERS:
         ui.error(f"--status: use one of {', '.join(RUN_FILTERS)}.")
@@ -574,7 +693,20 @@ def logs(
         help="Where to save the .tar.gz (default run-<job>-logs.tar.gz here); - for stdout.",
     ),
 ) -> None:
-    """Download a run's logs (its record, hold and log files) as one .tar.gz, from any workspace."""
+    """Download a run's logs, from any workspace, as one .tar.gz file.
+
+    The file holds the run's record and credit hold, its status files, each stage's log, the training pods'
+    output and the calls it made through connections. Give the job ID or the start of it (as
+    `corethink admin runs` shows it). It is saved as `run-JOB-logs.tar.gz` in the current folder unless
+    `--output` names another file; `--output -` writes it to stdout.
+
+    With `--json` it returns `jobId`, `path` and `bytes`.
+
+    Examples:
+      corethink admin logs 3f2a
+      corethink admin logs 3f2a -o run.tar.gz
+      corethink admin logs 3f2a -o - | tar -tz
+    """
     job = job_id.strip().lower()
     if not JOB_ID.fullmatch(job):
         every = _call("GET", "/api/v1/admin/runs", qa=1).get("runs") or []
@@ -610,7 +742,14 @@ def superadmins_default(ctx: typer.Context) -> None:
 
 @superadmins_app.command("list")
 def superadmins_list() -> None:
-    """The super admins."""
+    """List the super admins.
+
+    Shows each super admin's email (yours marked), whether they are a team owner, have joined or have not
+    signed up yet, who added them and when. With `--json` it returns `admins` and `you`.
+
+    Examples:
+      corethink admin superadmins list
+    """
     data = _call("GET", "/api/v1/admin/superadmins")
     you = data.get("you")
 
@@ -640,7 +779,16 @@ def superadmins_add(
     email: str = typer.Argument(..., help="Their email address."),
     notify: bool = typer.Option(False, "--notify", help="Also email them that they were added (off by default)."),
 ) -> None:
-    """Make someone a super admin. They get access once they sign up with this email."""
+    """Make someone a super admin.
+
+    They get access to the admin commands and page once they sign up with this email. No email is sent
+    unless `--notify` is given. It does not ask for confirmation. Check the list with
+    `corethink admin superadmins list`.
+
+    Examples:
+      corethink admin superadmins add ana@acme.com
+      corethink admin superadmins add ana@acme.com --notify
+    """
     done = _call("POST", "/api/v1/admin/superadmins", {"email": email.strip(), "notify": notify})
     ui.emit(
         done,
@@ -655,7 +803,14 @@ def superadmins_remove(
     email: str = typer.Argument(..., help="Their email address."),
     yes: bool = YES_OPTION,
 ) -> None:
-    """Take away someone's super admin access."""
+    """Take away someone's super admin access.
+
+    Asks for confirmation unless `--yes` is given. The Workbench's team owners cannot be removed, and you
+    cannot remove yourself.
+
+    Examples:
+      corethink admin superadmins remove ana@acme.com
+    """
     ui.confirm(f"Remove {email.strip()} as a super admin?", yes=yes)
     done = _call("DELETE", "/api/v1/admin/superadmins", {"email": email.strip()})
     ui.emit(
@@ -671,7 +826,17 @@ def superadmins_remove(
 def waitlist(
     pending: bool = typer.Option(False, "--pending", help="Only people not sent the beta email yet."),
 ) -> None:
-    """The waitlist: who asked to join and who was sent the beta email (read only)."""
+    """Show the waitlist: who asked to join and who got the beta email.
+
+    Shows whether sign-up is open to everyone or by invitation only, then each person's email (test
+    addresses marked), where they came from, when they joined the waitlist and when they were sent the beta
+    email. `--pending` keeps only people not sent it yet. This command only reads; it sends nothing.
+
+    With `--json` it returns `open` and `entries`.
+
+    Examples:
+      corethink admin waitlist --pending
+    """
     data = _call("GET", "/api/v1/waitlist")
     entries = [e for e in data.get("entries") or [] if not pending or not e.get("invitedAt")]
 

{corethink-1.0.0 → corethink-1.0.2}/src/corethink/commands/api.py

@@ -22,7 +22,17 @@ def api(
 ) -> None:
     """Call any Workbench API route directly and print its JSON answer.
 
-    Example: corethink api GET /api/v1/harnesses/training-jobs -p qa=1
+    For what the other commands do not cover yet: everything the console does goes through this API, and this command
+    calls it as you, with your session, in the open workspace. A path without `/api/` is taken as under `/api/v1/`.
+    The answer is printed as JSON whatever `--json` says; an error answer exits with the error's message.
+
+    It does what the route does: a POST, PUT, PATCH or DELETE changes things (and may spend credit) as the same
+    action in the console would. Prefer the named commands when there is one.
+
+    Examples:
+      corethink api GET /api/v1/harnesses/training-jobs -p qa=1
+      corethink api GET harnesses/usecases
+      corethink api POST harnesses/training-jobs -d @run.json
     """
     verb = method.upper()
     if verb not in METHODS:

{corethink-1.0.0 → corethink-1.0.2}/src/corethink/commands/archive.py

@@ -27,8 +27,28 @@ from corethink.commands.train import (
 )
 from corethink.context import client
 
+HELP = """Archived runs, tests and environments: restore them, or delete them for good.
+
+Archiving takes a finished run or test, or a whole environment, out of the lists without losing anything:
+`corethink train archive` archives a run or test, and `corethink env archive` an environment with every
+run and test on it. An archived run's or environment's endpoint keeps serving what it served when it was
+archived. Archiving can be undone at any time with `corethink archive restore`.
+
+Deleting is different: `corethink archive delete` and `corethink archive delete-all` remove archived
+things for good, with their logs, files and endpoints, and cannot be undone. Only archived things can be
+deleted, and only admins can delete. Each delete first shows what it would remove and asks you to
+confirm. Credit already spent stays in the ledger.
+
+Members can restore runs and tests; restoring an environment needs an admin.
+
+Examples:
+  corethink archive list
+  corethink archive restore 3f2a
+  corethink archive delete 3f2a
+"""
+
 app = typer.Typer(
-    help="Archived runs, tests and environments: restore them, or delete them for good.",
+    help=HELP,
     no_args_is_help=True,
     rich_markup_mode="rich",
 )
@@ -68,9 +88,19 @@ def _archived(at: Any, by: Any) -> str:
 
 @app.command("list")
 def list_archive() -> None:
-    """Archived environments, runs and tests in this workspace.
+    """List the archived environments, runs and tests in this workspace.
+
+    Archived environments show their ID, name, how many runs and tests were archived with them, and when
+    and by whom they were archived. Archived runs and tests show their ID, name, kind (training run or
+    base-model test), environment, result (a finished run's score before and after training, or a test's
+    score) and when they were archived, noting those archived with their environment.
+
+    With `--json` it returns `environments` and `runs`. Bring one back with `corethink archive restore`,
+    or remove it for good with `corethink archive delete`.
 
-    Example: corethink archive list
+    Examples:
+      corethink archive list
+      corethink --json archive list
     """
     archive = load_archive()
 
@@ -198,7 +228,14 @@ def restore(
     environment: bool = typer.Option(False, "--env", help="It is an environment."),
     run: bool = typer.Option(False, "--run", help="It is a run or test."),
 ) -> None:
-    """Bring an archived run, test or environment back (an environment comes back with the runs archived with it).
+    """Bring back an archived run, test or environment.
+
+    It returns to the lists as it was. An environment comes back with the runs and tests archived with it.
+    A run or test whose environment is archived cannot come back alone: restore the environment instead.
+    Members can restore runs and tests; restoring an environment needs an admin.
+
+    Give the ID or its start, or a run's name, as `corethink archive list` shows it. Environments are
+    matched first; `--env` or `--run` says which kind you mean.
 
     Examples:
       corethink archive restore 3f2a
@@ -287,12 +324,22 @@ def delete(
     run: bool = typer.Option(False, "--run", help="It is a run or test."),
     yes: bool = typer.Option(False, "--yes", "-y", help="Delete without asking."),
 ) -> None:
-    """Delete an archived run, test or environment for good (admins). Shows what would go first.
+    """Delete an archived run, test or environment for good (admins).
+
+    First shows what would be removed, as the Workbench counts it. For a run or test: its record, logs,
+    charts, final check and files, and its learned program's package with what its endpoint serves from
+    it, unless something else still uses them. An environment also takes its archived runs and tests, its
+    endpoint (staging, canaries and keys: callers using those keys stop working) and its own files (tasks,
+    tools, traces, captured conversations and labels).
 
-    An environment takes its archived runs and tests, its endpoint (staging, keys) and its files with it.
-    This cannot be undone.
+    Then you confirm by typing the run's short ID (its first 8 characters) or the environment's ID. `--yes`
+    skips this, and is required when there is no terminal to type in. This cannot be undone. Only archived
+    things can be deleted, and the Workbench may refuse, saying why. With `--json` it returns the summary
+    of what was deleted.
 
-    Example: corethink archive delete 3f2a
+    Examples:
+      corethink archive delete 3f2a
+      corethink archive delete payroll-0ecb50 --env --yes
     """
     if environment and run:
         raise fail("Choose --env or --run, not both.")
@@ -360,11 +407,19 @@ def delete_all(
     what: str = typer.Argument(..., help="runs (archived runs and tests) or environments."),
     yes: bool = typer.Option(False, "--yes", "-y", help="Delete without asking."),
 ) -> None:
-    """Delete every archived run and test, or every archived environment, for good (admins).
+    """Delete every archived run and test, or every archived environment (admins).
+
+    Say `runs` (archived runs and tests) or `environments`. It first shows what would be removed, then asks:
+    a yes-or-no question for runs; for environments you type `delete all`. `--yes` skips this, and is
+    required when there is no terminal. This cannot be undone. Credit already spent stays in the ledger.
 
-    Any that cannot be deleted are skipped and listed. Spent credit stays in the ledger. This cannot be undone.
+    They are deleted a few at a time. Any that cannot be deleted are skipped and listed with the reason,
+    and the command then exits with status 1. With `--json` it returns `asked`, `deleted`, `failed` (each
+    with its reason) and `stopped` (why it stopped early, if it did).
 
-    Example: corethink archive delete-all runs
+    Examples:
+      corethink archive delete-all runs
+      corethink archive delete-all environments --yes
     """
     if what not in ("runs", "environments"):
         raise fail("Say what to delete: runs or environments.")