minitest-cli 0.40.0__tar.gz → 0.41.0__tar.gz

{minitest_cli-0.40.0 → minitest_cli-0.41.0}/.env.example

@@ -24,7 +24,7 @@ MINITEST_CONDUCTOR_URL=https://conductor.dev.minitap.ai
 
 # —— Integrations ——
 # Production
-# MINITEST_INTEGRATIONS_URL=https://integrations.minitap.ai
+# MINITEST_INTEGRATIONS_URL=https://integrations.app.minitap.ai
 # Development
 MINITEST_INTEGRATIONS_URL=https://integrations.dev.minitap.ai
 

{minitest_cli-0.40.0 → minitest_cli-0.41.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: minitest-cli
-Version: 0.40.0
+Version: 0.41.0
 Summary: Minitest CLI – command-line interface for the Minitest testing platform
 Project-URL: Homepage, https://minitap.ai/
 Project-URL: Source, https://github.com/minitap-ai/minitest-cli
@@ -23,6 +23,7 @@ Requires-Python: >=3.12
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: pydantic-settings>=2.13.1
 Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: rich>=14.3.3
 Requires-Dist: typer>=0.24.1
 Provides-Extra: dev
@@ -214,12 +215,18 @@ app defaults.
 | `minitest df` | Low-level suite branches Mini writes (draft features) |
 | `minitest test-profile` | Test profiles (Test accounts in the webapp) |
 | `minitest tags`  | List, create, update and delete scenario tags |
+| `minitest brief` | Product brief: what the app is, who uses it, its core flows (Knowledge v2) |
+| `minitest app-guide` | App guide: how to use the app when testing it (Knowledge v2) |
+| `minitest glossary` | Glossary: product terms, their meaning and aliases (Knowledge v2) |
+| `minitest knowledge` | Change history of the brief, app guide and glossary, and reverts |
+| `minitest app-knowledge` | The single Memory document of workspaces without Knowledge v2 |
 | `minitest app-skill` | App skills (Skills in the webapp): procedures Mini loads to arrange test state |
 | `minitest secret` | App secrets vault: passwords, OTP seeds, cards, API tokens referenced as `{{secret:NAME}}` (write-only values) |
 | `minitest screens` | Inspect the screens exploration mapped for an app |
 | `minitest build` | Native iOS/Android build management |
 | `minitest run`   | Start runs and inspect their scenario runs |
 | `minitest batch` | List, inspect and cancel runs (a batch is a Run in the webapp) |
+| `minitest schedules` | Scheduled runs: run scenarios at a set time and post a Slack summary |
 | `minitest issues` | Read app issues and their fix prompts, mark them fixed |
 | `minitest skill` | Print the CLI skill for your AI coding agent (not app skills) |
 
@@ -240,6 +247,65 @@ stderr and leave `--json` stdout unchanged. Switch to the new names.
 | `run cancel --srp`, `run recording --srp` | `--target-id` |
 | `--type` on `scenario create/update/list` | `--tag` |
 
+## Scheduled runs
+
+A schedule starts an ordinary run on its own at a wall-clock time on chosen
+weekdays, then posts one summary to a Slack channel. What runs (the whole suite,
+tags minus exclusions, or picked scenarios) is re-resolved at every start, so
+scenarios tagged later join on their own.
+
+```bash
+# Weekdays at 03:00 (this machine's timezone), tagged scenarios on desktop and Android Chrome
+minitest schedules create --name "Nightly sanity check" --at 03:00 \
+  --tag Navigation --exclude "Deals page opens" \
+  --url https://www.example.com --browser chrome --browser chrome:android \
+  --slack-channel C0123ABCD --slack-channel-name minitap
+
+# Native: newest installable build on Android, a fixed iOS build, every day in Oslo
+minitest schedules create --name "Monitoring" --at 05:00 --days every-day --timezone Europe/Oslo \
+  --android --ios-build <build-id> --slack-channel C0123ABCD
+
+minitest schedules preview "Nightly sanity check"     # duration, builds tonight would pick, next starts
+minitest schedules list                               # cadence, next run, scenario count
+minitest --json schedules get "Nightly sanity check" > nightly.json
+minitest schedules create --from-file nightly.json --name "Nightly copy"   # JSON or YAML
+minitest schedules update "Nightly sanity check" --at 04:00 --android-branch main
+minitest schedules pause|resume "Nightly sanity check"
+minitest schedules run "Nightly sanity check"         # start one now (posts to Slack too)
+minitest schedules fires "Nightly sanity check"       # last runs: verdict, new / still open / fixed, or why it didn't run
+minitest schedules delete "Nightly sanity check" --yes   # `schedules restore <id>` undoes it
+```
+
+Platforms: `--browser BROWSER[:SURFACE]` (`chrome`, `chrome:mobile`,
+`chrome:tablet`, `chrome:android`, `safari:ios`…) tests `--url` or builds
+`--web-branch` first. `--ios` / `--android` run the newest build that installs;
+`--<platform>-build <id>` pins one build, `--<platform>-branch <branch>` builds
+the branch before each run. On `update`, any `--<platform>-*` flag redefines that
+platform, `--browser` replaces the browsers, `--drop web|ios|android` removes one.
+
+A night that can't run is still a fire, with a reason (out of credits, no
+installable build, branch build failed, previous run still going, no phone
+free…); `fires` shows it and Slack gets a message. On a server without
+scheduled runs, every command exits 4 with `Scheduled runs are not available
+on this workspace yet.`
+
+## Knowledge
+
+On workspaces with Knowledge v2, what Mini knows about an app is split by job:
+
+| Element | Holds | Commands |
+| ------- | ----- | -------- |
+| Product brief | What the app is, who uses it, its core flows. Short (max 2000 chars). | `brief get`, `brief update --content/--content-file` |
+| App guide | How to use the app when testing: navigation, quirks, test data. | `app-guide get`, `app-guide update --content/--content-file` |
+| Glossary | Product terms and what they mean, with aliases. | `glossary list`, `glossary add --term --meaning [--alias]`, `glossary update <id-or-term>`, `glossary remove <id-or-term> --yes` |
+
+Every change is versioned with its author and channel (`cli` for these
+commands): `minitest knowledge history [--element product_brief|app_guide|glossary]`
+lists each change with its version ID, and `minitest knowledge revert <version-id>`
+restores that version as a new `reverted` change.
+On a workspace without Knowledge v2, writes fail with a message pointing to
+`minitest app-knowledge`.
+
 ## Secrets
 
 Credentials live in the app's vault, never in scenario text. Write
@@ -250,18 +316,26 @@ Workspaces without the feature get `Secrets are not enabled for this workspace y
 
 ```bash
 printf '%s' "$ADMIN_PW" | minitest secret set ADMIN_PASSWORD --kind password --note "Admin login"
-echo '{"number":"4242424242424242","expiry":"12/34","cvc":"123"}' \
+echo '{"number":"<number>","expiry":"<MM/YY>","cvc":"<cvc>"}' \
   | minitest secret set STRIPE_CARD --kind card          # optional holder_name, postal_code
-minitest secret list [--missing]                         # names, kinds, usages, requests
+minitest secret create QA_PASSWORD --kind password --generate [--length 24] [--charset default|alnum]
+minitest secret create SANDBOX_KEY --kind token --empty --reason "Checkout calls the sandbox" [--scenario <id>]
+minitest secret list [--missing]                         # names, kinds, state (set / missing + reason), usages
 minitest secret describe ADMIN_PASSWORD                  # usages + reference to copy
-minitest secret lint --scenario <id>                     # exit 1 on leaks or missing secrets
+minitest secret lint --scenario <id>                     # exit 1 on leaks or missing; warns on pending
 minitest secret extract <id> --as ADMIN_PASSWORD --kind password [--dry-run]
 minitest test-profile update <id> --password-secret ADMIN_PASSWORD
 ```
 
 `set` reads stdin only and refuses a terminal (`--interactive` opens a hidden
-prompt). Inside a test run (`MINITAP_SECRETS_SOCKET` or `STORY_RUN_ID` set) it
-refuses: use `minitest secret request NAME --kind <kind> --reason "…"` instead.
+prompt) and also fills a secret that is waiting for a value. Inside a test run
+(`MINITAP_SECRETS_SOCKET` or `STORY_RUN_ID` set) it refuses: use `secret create`
+instead, which never handles a value. `--generate` (password, token, text) lets
+the server pick a random value (default 24 chars, 12–64); `--empty --reason`
+creates the secret without a value for a human to fill, and runs that need it
+wait until then. Personas can point at either (`--password-secret` etc.).
+`secret request` is a deprecated alias of `create --empty`; on servers that
+predate `create`, `--empty` falls back to the old request endpoint.
 `extract` reads the leaked literal from the scenario on your machine, creates
 the secret with it, then rewrites every occurrence to `{{secret:NAME}}`. Older
 scenario versions and past run logs may still hold the literal: rotate it.

{minitest_cli-0.40.0 → minitest_cli-0.41.0}/README.md

@@ -181,12 +181,18 @@ app defaults.
 | `minitest df` | Low-level suite branches Mini writes (draft features) |
 | `minitest test-profile` | Test profiles (Test accounts in the webapp) |
 | `minitest tags`  | List, create, update and delete scenario tags |
+| `minitest brief` | Product brief: what the app is, who uses it, its core flows (Knowledge v2) |
+| `minitest app-guide` | App guide: how to use the app when testing it (Knowledge v2) |
+| `minitest glossary` | Glossary: product terms, their meaning and aliases (Knowledge v2) |
+| `minitest knowledge` | Change history of the brief, app guide and glossary, and reverts |
+| `minitest app-knowledge` | The single Memory document of workspaces without Knowledge v2 |
 | `minitest app-skill` | App skills (Skills in the webapp): procedures Mini loads to arrange test state |
 | `minitest secret` | App secrets vault: passwords, OTP seeds, cards, API tokens referenced as `{{secret:NAME}}` (write-only values) |
 | `minitest screens` | Inspect the screens exploration mapped for an app |
 | `minitest build` | Native iOS/Android build management |
 | `minitest run`   | Start runs and inspect their scenario runs |
 | `minitest batch` | List, inspect and cancel runs (a batch is a Run in the webapp) |
+| `minitest schedules` | Scheduled runs: run scenarios at a set time and post a Slack summary |
 | `minitest issues` | Read app issues and their fix prompts, mark them fixed |
 | `minitest skill` | Print the CLI skill for your AI coding agent (not app skills) |
 
@@ -207,6 +213,65 @@ stderr and leave `--json` stdout unchanged. Switch to the new names.
 | `run cancel --srp`, `run recording --srp` | `--target-id` |
 | `--type` on `scenario create/update/list` | `--tag` |
 
+## Scheduled runs
+
+A schedule starts an ordinary run on its own at a wall-clock time on chosen
+weekdays, then posts one summary to a Slack channel. What runs (the whole suite,
+tags minus exclusions, or picked scenarios) is re-resolved at every start, so
+scenarios tagged later join on their own.
+
+```bash
+# Weekdays at 03:00 (this machine's timezone), tagged scenarios on desktop and Android Chrome
+minitest schedules create --name "Nightly sanity check" --at 03:00 \
+  --tag Navigation --exclude "Deals page opens" \
+  --url https://www.example.com --browser chrome --browser chrome:android \
+  --slack-channel C0123ABCD --slack-channel-name minitap
+
+# Native: newest installable build on Android, a fixed iOS build, every day in Oslo
+minitest schedules create --name "Monitoring" --at 05:00 --days every-day --timezone Europe/Oslo \
+  --android --ios-build <build-id> --slack-channel C0123ABCD
+
+minitest schedules preview "Nightly sanity check"     # duration, builds tonight would pick, next starts
+minitest schedules list                               # cadence, next run, scenario count
+minitest --json schedules get "Nightly sanity check" > nightly.json
+minitest schedules create --from-file nightly.json --name "Nightly copy"   # JSON or YAML
+minitest schedules update "Nightly sanity check" --at 04:00 --android-branch main
+minitest schedules pause|resume "Nightly sanity check"
+minitest schedules run "Nightly sanity check"         # start one now (posts to Slack too)
+minitest schedules fires "Nightly sanity check"       # last runs: verdict, new / still open / fixed, or why it didn't run
+minitest schedules delete "Nightly sanity check" --yes   # `schedules restore <id>` undoes it
+```
+
+Platforms: `--browser BROWSER[:SURFACE]` (`chrome`, `chrome:mobile`,
+`chrome:tablet`, `chrome:android`, `safari:ios`…) tests `--url` or builds
+`--web-branch` first. `--ios` / `--android` run the newest build that installs;
+`--<platform>-build <id>` pins one build, `--<platform>-branch <branch>` builds
+the branch before each run. On `update`, any `--<platform>-*` flag redefines that
+platform, `--browser` replaces the browsers, `--drop web|ios|android` removes one.
+
+A night that can't run is still a fire, with a reason (out of credits, no
+installable build, branch build failed, previous run still going, no phone
+free…); `fires` shows it and Slack gets a message. On a server without
+scheduled runs, every command exits 4 with `Scheduled runs are not available
+on this workspace yet.`
+
+## Knowledge
+
+On workspaces with Knowledge v2, what Mini knows about an app is split by job:
+
+| Element | Holds | Commands |
+| ------- | ----- | -------- |
+| Product brief | What the app is, who uses it, its core flows. Short (max 2000 chars). | `brief get`, `brief update --content/--content-file` |
+| App guide | How to use the app when testing: navigation, quirks, test data. | `app-guide get`, `app-guide update --content/--content-file` |
+| Glossary | Product terms and what they mean, with aliases. | `glossary list`, `glossary add --term --meaning [--alias]`, `glossary update <id-or-term>`, `glossary remove <id-or-term> --yes` |
+
+Every change is versioned with its author and channel (`cli` for these
+commands): `minitest knowledge history [--element product_brief|app_guide|glossary]`
+lists each change with its version ID, and `minitest knowledge revert <version-id>`
+restores that version as a new `reverted` change.
+On a workspace without Knowledge v2, writes fail with a message pointing to
+`minitest app-knowledge`.
+
 ## Secrets
 
 Credentials live in the app's vault, never in scenario text. Write
@@ -217,18 +282,26 @@ Workspaces without the feature get `Secrets are not enabled for this workspace y
 
 ```bash
 printf '%s' "$ADMIN_PW" | minitest secret set ADMIN_PASSWORD --kind password --note "Admin login"
-echo '{"number":"4242424242424242","expiry":"12/34","cvc":"123"}' \
+echo '{"number":"<number>","expiry":"<MM/YY>","cvc":"<cvc>"}' \
   | minitest secret set STRIPE_CARD --kind card          # optional holder_name, postal_code
-minitest secret list [--missing]                         # names, kinds, usages, requests
+minitest secret create QA_PASSWORD --kind password --generate [--length 24] [--charset default|alnum]
+minitest secret create SANDBOX_KEY --kind token --empty --reason "Checkout calls the sandbox" [--scenario <id>]
+minitest secret list [--missing]                         # names, kinds, state (set / missing + reason), usages
 minitest secret describe ADMIN_PASSWORD                  # usages + reference to copy
-minitest secret lint --scenario <id>                     # exit 1 on leaks or missing secrets
+minitest secret lint --scenario <id>                     # exit 1 on leaks or missing; warns on pending
 minitest secret extract <id> --as ADMIN_PASSWORD --kind password [--dry-run]
 minitest test-profile update <id> --password-secret ADMIN_PASSWORD
 ```
 
 `set` reads stdin only and refuses a terminal (`--interactive` opens a hidden
-prompt). Inside a test run (`MINITAP_SECRETS_SOCKET` or `STORY_RUN_ID` set) it
-refuses: use `minitest secret request NAME --kind <kind> --reason "…"` instead.
+prompt) and also fills a secret that is waiting for a value. Inside a test run
+(`MINITAP_SECRETS_SOCKET` or `STORY_RUN_ID` set) it refuses: use `secret create`
+instead, which never handles a value. `--generate` (password, token, text) lets
+the server pick a random value (default 24 chars, 12–64); `--empty --reason`
+creates the secret without a value for a human to fill, and runs that need it
+wait until then. Personas can point at either (`--password-secret` etc.).
+`secret request` is a deprecated alias of `create --empty`; on servers that
+predate `create`, `--empty` falls back to the old request endpoint.
 `extract` reads the leaked literal from the scenario on your machine, creates
 the secret with it, then rewrites every occurrence to `{{secret:NAME}}`. Older
 scenario versions and past run logs may still hold the literal: rotate it.

{minitest_cli-0.40.0 → minitest_cli-0.41.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "minitest-cli"
-version = "0.40.0"
+version = "0.41.0"
 description = "Minitest CLI – command-line interface for the Minitest testing platform"
 readme = "README.md"
 license = "MIT"
@@ -32,6 +32,7 @@ dependencies = [
     "pydantic>=2.12.5",
     "pydantic-settings>=2.13.1",
     "rich>=14.3.3",
+    "pyyaml>=6.0.3",
 ]
 
 [project.optional-dependencies]

minitest_cli-0.41.0/src/minitest_cli/commands/glossary.py

@@ -0,0 +1,140 @@
+"""`minitest glossary`: the app's product terms, their meaning and aliases."""
+
+from typing import Annotated, Any
+
+import typer
+
+from minitest_cli.api.client import ApiClient
+from minitest_cli.commands.knowledge_helpers import (
+    app_path,
+    call_for_app,
+    check_response,
+    describe_actor,
+)
+from minitest_cli.commands.user_story_helpers import EXIT_NOT_FOUND, is_json_mode
+from minitest_cli.utils.confirm import confirm_or_exit
+from minitest_cli.utils.output import output, print_error, print_info, print_success, print_table
+
+app = typer.Typer(
+    name="glossary",
+    help="Glossary: product terms Mini must understand, with their meaning and aliases.",
+    no_args_is_help=True,
+)
+
+TermRef = Annotated[str, typer.Argument(help="Term ID, or the term itself (case-insensitive).")]
+AliasOption = Annotated[
+    list[str] | None,
+    typer.Option("--alias", help="Other name for the term (repeatable; replaces the aliases)."),
+]
+
+
+async def _fetch_terms(client: ApiClient, app_id: str) -> list[dict[str, Any]]:
+    resp = await client.get(app_path(app_id, "glossary"))
+    check_response(resp, resource="Glossary")
+    return resp.json().get("terms", [])
+
+
+def _find_term(terms: list[dict[str, Any]], ref: str) -> dict[str, Any]:
+    wanted = ref.strip().casefold()
+    for term in terms:
+        if term.get("id") == ref or str(term.get("term", "")).casefold() == wanted:
+            return term
+    print_error(f"Glossary term not found: {ref}. Run `minitest glossary list` to see the terms.")
+    raise typer.Exit(code=EXIT_NOT_FOUND)
+
+
+@app.command(name="list")
+def list_terms() -> None:
+    """List every term with its meaning, aliases and last author."""
+    terms = call_for_app(_fetch_terms)
+    if is_json_mode():
+        output({"terms": terms}, json_mode=True)
+        return
+    if not terms:
+        print_info("No glossary terms yet. Add one with `minitest glossary add`.")
+        return
+    rows = [
+        [
+            t.get("term", ""),
+            t.get("meaning", ""),
+            ", ".join(t.get("aliases") or []),
+            describe_actor(t.get("actor")),
+            t.get("id", ""),
+        ]
+        for t in terms
+    ]
+    print_table(["Term", "Meaning", "Aliases", "Last edited by", "ID"], rows, title="Glossary")
+
+
+@app.command(name="add")
+def add_term(
+    term: Annotated[str, typer.Option("--term", help="The product term, as users say it.")],
+    meaning: Annotated[str, typer.Option("--meaning", help="What the term means in this app.")],
+    alias: AliasOption = None,
+) -> None:
+    """Add a term to the glossary."""
+    body = {"term": term, "meaning": meaning, "aliases": alias or []}
+
+    async def _add(client: ApiClient, app_id: str) -> dict[str, Any]:
+        resp = await client.post(app_path(app_id, "glossary"), json=body)
+        check_response(resp, resource="Glossary")
+        return resp.json()
+
+    created = call_for_app(_add)
+    if not is_json_mode():
+        print_success(f"Glossary term added: {created.get('term')} ({created.get('id')})")
+    output(created, json_mode=is_json_mode())
+
+
+@app.command(name="update")
+def update_term(
+    term_ref: TermRef,
+    term: Annotated[str | None, typer.Option("--term", help="Rename the term.")] = None,
+    meaning: Annotated[str | None, typer.Option("--meaning", help="New meaning.")] = None,
+    alias: AliasOption = None,
+    clear_aliases: Annotated[
+        bool, typer.Option("--clear-aliases", help="Remove every alias. Excludes --alias.")
+    ] = False,
+) -> None:
+    """Change a term's name, meaning or aliases."""
+    if clear_aliases and alias:
+        print_error("Use either --alias or --clear-aliases, not both.")
+        raise typer.Exit(code=1)
+    fields: dict[str, Any] = {"term": term, "meaning": meaning}
+    fields["aliases"] = [] if clear_aliases else alias or None
+    payload = {key: value for key, value in fields.items() if value is not None}
+    if not payload:
+        print_error("Provide at least one of --term, --meaning, --alias or --clear-aliases.")
+        raise typer.Exit(code=1)
+
+    async def _update(client: ApiClient, app_id: str) -> dict[str, Any]:
+        found = _find_term(await _fetch_terms(client, app_id), term_ref)
+        resp = await client.patch(app_path(app_id, f"glossary/{found['id']}"), json=payload)
+        check_response(resp, resource="Glossary term")
+        return resp.json()
+
+    updated = call_for_app(_update)
+    if not is_json_mode():
+        print_success(f"Glossary term updated: {updated.get('term')}")
+    output(updated, json_mode=is_json_mode())
+
+
+@app.command(name="remove")
+def remove_term(
+    term_ref: TermRef,
+    yes: Annotated[bool, typer.Option("--yes", help="Confirm the removal.")] = False,
+) -> None:
+    """Remove a term from the glossary (kept in its history)."""
+    confirm_or_exit(yes, f"Removing glossary term {term_ref!r}")
+
+    async def _remove(client: ApiClient, app_id: str) -> dict[str, Any]:
+        found = _find_term(await _fetch_terms(client, app_id), term_ref)
+        resp = await client.delete(app_path(app_id, f"glossary/{found['id']}"))
+        check_response(resp, resource="Glossary term")
+        return found
+
+    removed = call_for_app(_remove)
+    if is_json_mode():
+        output({"removed": True, "id": removed["id"], "term": removed["term"]}, json_mode=True)
+    else:
+        print_success(f"Glossary term removed: {removed['term']}")

minitest_cli-0.41.0/src/minitest_cli/commands/knowledge.py

@@ -0,0 +1,105 @@
+"""`minitest knowledge history|revert`: who changed the Product brief, App guide or Glossary."""
+
+from enum import StrEnum
+from typing import Annotated, Any
+
+import typer
+
+from minitest_cli.api.client import ApiClient
+from minitest_cli.commands.knowledge_helpers import (
+    app_path,
+    call_for_app,
+    check_response,
+    describe_actor,
+)
+from minitest_cli.commands.user_story_helpers import is_json_mode
+from minitest_cli.utils.output import output, print_info, print_success, print_table
+
+app = typer.Typer(
+    name="knowledge",
+    help="Change history of the Product brief, App guide and Glossary, and reverts.",
+    no_args_is_help=True,
+)
+
+
+class KnowledgeElement(StrEnum):
+    product_brief = "product_brief"
+    app_guide = "app_guide"
+    glossary = "glossary"
+
+
+@app.callback()
+def _callback() -> None:
+    """Knowledge operations."""
+
+
+@app.command(name="history")
+def history(
+    element: Annotated[
+        KnowledgeElement | None,
+        typer.Option("--element", help="Only this element (default: all three, merged)."),
+    ] = None,
+    limit: Annotated[int, typer.Option("--limit", min=1, max=200, help="Max changes.")] = 20,
+) -> None:
+    """List recent changes, newest first, with author, channel and version."""
+    elements = [element] if element else list(KnowledgeElement)
+
+    async def _history(client: ApiClient, app_id: str) -> list[dict[str, Any]]:
+        changes: list[dict[str, Any]] = []
+        for wanted in elements:
+            resp = await client.get(
+                app_path(app_id, "knowledge/history"),
+                params={"element": wanted.value, "limit": limit},
+            )
+            check_response(resp, resource="Knowledge history")
+            changes.extend(resp.json())
+        changes.sort(key=lambda change: change.get("createdAt") or "", reverse=True)
+        return changes[:limit]
+
+    changes = call_for_app(_history)
+    if is_json_mode():
+        output(changes, json_mode=True)
+        return
+    if not changes:
+        print_info("No knowledge changes yet.")
+        return
+    rows = [
+        [
+            c.get("createdAt", ""),
+            c.get("element", ""),
+            c.get("change", ""),
+            _subject(c),
+            describe_actor(c.get("actor")),
+            c.get("versionId", ""),
+        ]
+        for c in changes
+    ]
+    print_table(["When", "Element", "Change", "Version / term", "By", "Version ID"], rows)
+
+
+def _subject(change: dict[str, Any]) -> str:
+    if change.get("versionNumber") is not None:
+        return f"v{change['versionNumber']}"
+    after = change.get("after") if isinstance(change.get("after"), dict) else None
+    before = change.get("before") if isinstance(change.get("before"), dict) else None
+    snapshot = after or before or {}
+    return str(snapshot.get("term") or change.get("termId") or "")
+
+
+@app.command(name="revert")
+def revert(
+    version_id: Annotated[
+        str, typer.Argument(help="Version ID from `minitest knowledge history`.")
+    ],
+) -> None:
+    """Restore an element to that version, recorded as a new 'reverted' change."""
+
+    async def _revert(client: ApiClient, app_id: str) -> None:
+        resp = await client.post(app_path(app_id, f"knowledge/history/{version_id}/revert"))
+        check_response(resp, resource="Knowledge version")
+
+    call_for_app(_revert)
+    if is_json_mode():
+        output({"versionId": version_id, "reverted": True}, json_mode=True)
+        return
+    print_success(f"Reverted to version {version_id}.")

minitest_cli-0.41.0/src/minitest_cli/commands/knowledge_documents.py

@@ -0,0 +1,86 @@
+"""`minitest brief` and `minitest app-guide`: the two versioned Knowledge v2 documents."""
+
+from typing import Any
+
+import typer
+
+from minitest_cli.api.client import ApiClient
+from minitest_cli.commands.knowledge_helpers import (
+    ContentFileOption,
+    ContentOption,
+    app_path,
+    call_for_app,
+    check_response,
+    describe_actor,
+    resolve_content,
+)
+from minitest_cli.commands.user_story_helpers import is_json_mode
+from minitest_cli.utils.output import output, print_info, print_success
+
+
+def _document_app(name: str, route: str, label: str, help_text: str) -> typer.Typer:
+    group = typer.Typer(name=name, help=help_text, no_args_is_help=True)
+
+    @group.command(name="get")
+    def get_document() -> None:
+        """Print the current content (with --json: content, version and author)."""
+
+        async def _get(client: ApiClient, app_id: str) -> dict[str, Any]:
+            resp = await client.get(app_path(app_id, route))
+            check_response(resp, resource=label)
+            return resp.json()
+
+        record = call_for_app(_get)
+        if is_json_mode():
+            output(record, json_mode=True)
+            return
+        if not record.get("content"):
+            print_info(f"No {label} written yet.")
+            return
+        print_info(_version_line(record))
+        print(record["content"])  # noqa: T201
+
+    @group.command(name="update")
+    def update_document(
+        content: ContentOption = None, content_file: ContentFileOption = None
+    ) -> None:
+        """Replace the content, creating a new version authored by you via the CLI."""
+        body = {"content": resolve_content(content, content_file)}
+
+        async def _put(client: ApiClient, app_id: str) -> dict[str, Any]:
+            resp = await client.put(app_path(app_id, route), json=body)
+            check_response(resp, resource=label)
+            return resp.json()
+
+        record = call_for_app(_put)
+        if is_json_mode():
+            output(record, json_mode=True)
+            return
+        print_success(f"{label} updated (version {record.get('versionNumber')}).")
+        print(record.get("versionNumber"))  # noqa: T201
+
+    return group
+
+
+def _version_line(record: dict[str, Any]) -> str:
+    author = describe_actor(record.get("actor"))
+    line = f"Version {record.get('versionNumber')}"
+    if author:
+        line += f" by {author}"
+    if record.get("createdAt"):
+        line += f", {record['createdAt']}"
+    return line
+
+
+brief_app = _document_app(
+    "brief",
+    "product-brief",
+    "Product brief",
+    "Product brief: what the app is, who uses it and its core flows (max 2000 chars).",
+)
+app_guide_app = _document_app(
+    "app-guide",
+    "app-guide",
+    "App guide",
+    "App guide: how to use the app when testing it (navigation, quirks, test data).",
+)