systemlink-cli 1.27.1__tar.gz → 1.27.3__tar.gz

{systemlink_cli-1.27.1 → systemlink_cli-1.27.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: systemlink-cli
-Version: 1.27.1
+Version: 1.27.3
 Summary: SystemLink Integrator CLI - cross-platform CLI for SystemLink workflows and templates.
 License-File: LICENSE
 Author: Fred Visser

{systemlink_cli-1.27.1 → systemlink_cli-1.27.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "systemlink-cli"
-version = "1.27.1"
+version = "1.27.3"
 description = "SystemLink Integrator CLI - cross-platform CLI for SystemLink workflows and templates."
 authors = ["Fred Visser <fred.visser@emerson.com>"]
 packages = [{ include = "slcli" }]

{systemlink_cli-1.27.1 → systemlink_cli-1.27.3}/slcli/_version.py

@@ -1,4 +1,4 @@
 """Version information for slcli."""
 
 # This file is auto-generated. Do not edit manually.
-__version__ = "1.27.1"
+__version__ = "1.27.3"

{systemlink_cli-1.27.1 → systemlink_cli-1.27.3}/slcli/main.py

@@ -43,6 +43,7 @@ from .templates_click import register_templates_commands
 from .testmonitor_click import register_testmonitor_commands
 from .user_click import register_user_commands
 from .utils import describe_config_source
+from .version_click import register_version_commands
 from .webapp_click import register_webapp_commands
 from .workitem_click import register_workitem_commands
 from .workspace_click import register_workspace_commands
@@ -71,7 +72,15 @@ def _configure_rich_click_command_groups() -> None:
         "slcli": [
             {
                 "name": "Configure",
-                "commands": ["config", "login", "logout", "info", "completion", "example"],
+                "commands": [
+                    "config",
+                    "login",
+                    "logout",
+                    "info",
+                    "version",
+                    "completion",
+                    "example",
+                ],
             },
             {
                 "name": "Administer",
@@ -363,7 +372,7 @@ def cli(ctx: base_click.Context, version: bool, profile: Optional[str]) -> None:
 
     # Check for mandatory migration BEFORE any command runs
     # Skip migration check only for version flag and config migrate command
-    if ctx.invoked_subcommand not in (None, "config"):
+    if ctx.invoked_subcommand not in (None, "config", "version"):
         from .profiles import ProfileConfig, has_keyring_credentials, migrate_from_keyring
 
         config_path = ProfileConfig.get_config_path()
@@ -769,5 +778,6 @@ register_testmonitor_commands(cli)
 register_webapp_commands(cli)
 register_skill_commands(cli)
 register_user_commands(cli)
+register_version_commands(cli)
 register_workitem_commands(cli)
 register_workspace_commands(cli)

{systemlink_cli-1.27.1 → systemlink_cli-1.27.3}/slcli/platform.py

@@ -168,8 +168,9 @@ def get_platform() -> str:
 
     Detection priority:
     1. SYSTEMLINK_PLATFORM environment variable (explicit, most reliable)
-    2. Stored platform from keyring config (set during login via endpoint probing)
-    3. Return PLATFORM_UNKNOWN if no explicit or stored platform is available
+    2. Platform stored on the active profile (set during login via endpoint probing)
+    3. Stored platform from keyring config (legacy fallback)
+    4. Return PLATFORM_UNKNOWN if no explicit or stored platform is available
 
     Note: Results are cached for performance. Use clear_platform_cache() to reset.
 
@@ -182,11 +183,26 @@ def get_platform() -> str:
     if env_platform in (PLATFORM_SLE, PLATFORM_SLS):
         return env_platform
 
-    # Priority 2: Stored platform from keyring config (set during login)
-    # This was detected via endpoint probing, which is reliable
+    if not any(os.environ.get(name) for name in ("SLCLI_API_URL", "SYSTEMLINK_API_URL")):
+        try:
+            from .profiles import get_active_profile
+
+            profile = get_active_profile()
+            profile_platform = str(profile.platform or "").upper() if profile else ""
+            if profile_platform in (PLATFORM_SLE, PLATFORM_SLS):
+                return profile_platform
+        except (
+            FileNotFoundError,
+            json.JSONDecodeError,
+            KeyError,
+            AttributeError,
+            click.ClickException,
+        ):
+            pass
+
     cfg = _get_keyring_config()
     if cfg:
-        platform = cfg.get("platform", "")
+        platform = str(cfg.get("platform", "")).upper()
         if platform in (PLATFORM_SLE, PLATFORM_SLS):
             return platform
 

{systemlink_cli-1.27.1 → systemlink_cli-1.27.3}/slcli/skill_click.py

@@ -6,11 +6,14 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
 import click
+from packaging.version import InvalidVersion, Version
 
+from ._version import __version__
 from .utils import ExitCodes, format_success
 
 SKILL_NAME = "slcli"
 _FALLBACK_SKILL_CHOICES = [SKILL_NAME]
+_VERSION_FILENAME = ".slcli-version"
 
 # Mapping of client name -> (personal skills dir, project subdir relative to repo root)
 # personal dir uses Path.home() so it's always resolved at call time via _personal_dir().
@@ -119,6 +122,23 @@ def _expand_skill_selection(skill_names: Optional[List[str]] = None) -> List[str
     return requested
 
 
+def _skill_installation_status(destination_root: Path, skill_name: str) -> str:
+    """Return the version status of an installed skill."""
+    destination_dir = destination_root / skill_name
+    if not destination_dir.exists():
+        return "missing"
+
+    version_file = destination_dir / _VERSION_FILENAME
+    if not version_file.exists():
+        return "unversioned"
+
+    try:
+        installed_version = version_file.read_text(encoding="utf-8").strip()
+        return "current" if Version(installed_version) >= Version(__version__) else "outdated"
+    except (InvalidVersion, OSError):
+        return "unversioned"
+
+
 def install_skills_to_directory(
     directory: Path,
     skill_names: Optional[List[str]] = None,
@@ -150,6 +170,7 @@ def install_skills_to_directory(
                 destination_dir.unlink()
 
         shutil.copytree(source_dir, destination_dir)
+        (destination_dir / _VERSION_FILENAME).write_text(f"{__version__}\n", encoding="utf-8")
 
     return len(selected_skills)
 
@@ -184,6 +205,19 @@ def _resolve_destinations(clients: List[str], scope: str) -> List[Path]:
     return seen
 
 
+def _requested_destinations(
+    directory: Optional[Path], client: Optional[str], scope: Optional[str]
+) -> List[Path]:
+    """Resolve either a custom skills directory or client-specific destinations."""
+    if directory is not None:
+        if client is not None or scope is not None:
+            raise ValueError("--directory cannot be combined with --client or --scope")
+        return [directory.expanduser()]
+
+    selected_clients = CLIENT_CHOICES if client == "all" else [client or "agents"]
+    return _resolve_destinations(selected_clients, scope or "project")
+
+
 def register_skill_commands(cli: Any) -> None:
     """Register the skill command group with the CLI.
 
@@ -217,6 +251,13 @@ def register_skill_commands(cli: Any) -> None:
         default=None,
         help="personal (~/ home dirs), project (current repo), or both.",
     )
+    @click.option(
+        "--directory",
+        "-d",
+        type=click.Path(file_okay=False, path_type=Path),
+        default=None,
+        help="Install directly into this skills directory.",
+    )
     @click.option(
         "--force",
         "-F",
@@ -225,7 +266,11 @@ def register_skill_commands(cli: Any) -> None:
         help="Overwrite existing skill installation without prompting.",
     )
     def install_skill(
-        skill: Optional[str], client: Optional[str], scope: Optional[str], force: bool
+        skill: Optional[str],
+        client: Optional[str],
+        scope: Optional[str],
+        directory: Optional[Path],
+        force: bool,
     ) -> None:
         """Install bundled skills for supported AI clients."""
         requested_skills: Optional[List[str]]
@@ -235,11 +280,9 @@ def register_skill_commands(cli: Any) -> None:
             assert skill is not None
             requested_skills = [skill.lower()]
         selected_skill_names = _expand_skill_selection(requested_skills)
-        selected_clients = CLIENT_CHOICES if client == "all" else [client or "agents"]
-        selected_scope = scope or "project"
-        destinations = _resolve_destinations(selected_clients, selected_scope)
 
         try:
+            destinations = _requested_destinations(directory, client, scope)
             installed_count = 0
             for destination in destinations:
                 installed_count += install_skills_to_directory(
@@ -257,6 +300,9 @@ def register_skill_commands(cli: Any) -> None:
         except FileNotFoundError as exc:
             click.echo(f"✗ {exc}", err=True)
             sys.exit(ExitCodes.GENERAL_ERROR)
+        except OSError as exc:
+            click.echo(f"✗ Unable to install skills: {exc}", err=True)
+            sys.exit(ExitCodes.GENERAL_ERROR)
 
         format_success(
             "Installed bundled AI skills",
@@ -266,3 +312,60 @@ def register_skill_commands(cli: Any) -> None:
                 "Installed": str(installed_count),
             },
         )
+
+    @skill.command(name="check")
+    @click.option(
+        "--skill",
+        "-k",
+        type=click.Choice(SKILL_CHOICES + ["all"], case_sensitive=False),
+        default=None,
+        help=f"Skill to check ({', '.join(SKILL_CHOICES)}, or all).",
+    )
+    @click.option(
+        "--client",
+        "-c",
+        type=click.Choice(CLIENT_CHOICES + ["all"], case_sensitive=False),
+        default=None,
+        help="AI client installation to check (agents, claude, or all).",
+    )
+    @click.option(
+        "--scope",
+        "-s",
+        type=click.Choice(["personal", "project", "both"], case_sensitive=False),
+        default=None,
+        help="personal (~/ home dirs), project (current repo), or both.",
+    )
+    @click.option(
+        "--directory",
+        "-d",
+        type=click.Path(file_okay=False, path_type=Path),
+        default=None,
+        help="Check skills directly in this directory.",
+    )
+    def check_skills(
+        skill: Optional[str],
+        client: Optional[str],
+        scope: Optional[str],
+        directory: Optional[Path],
+    ) -> None:
+        """Check whether installed skills match the bundled version."""
+        requested_skills = None if skill in (None, "all") else [skill.lower()]
+
+        try:
+            selected_skill_names = _expand_skill_selection(requested_skills)
+            destinations = _requested_destinations(directory, client, scope)
+        except ValueError as exc:
+            click.echo(f"✗ {exc}", err=True)
+            sys.exit(ExitCodes.INVALID_INPUT)
+
+        needs_update = False
+        click.echo(f"Bundled skill version: {__version__}")
+        for destination in destinations:
+            for skill_name in selected_skill_names:
+                status = _skill_installation_status(destination, skill_name)
+                indicator = "✓" if status == "current" else "✗"
+                click.echo(f"{indicator} {destination / skill_name}: {status}")
+                needs_update = needs_update or status != "current"
+
+        if needs_update:
+            sys.exit(ExitCodes.GENERAL_ERROR)

systemlink_cli-1.27.3/slcli/skills/slcli/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: slcli
+description: >-
+  Query and manage NI SystemLink resources using the slcli command-line interface.
+  Use when the user asks about test results, assets, systems, work items,
+  specifications, webapps, notebooks, dataframes, files, feeds, tags,
+  authorization, users, example fixture authoring, example config.yaml files,
+  or other SystemLink resource workflows. Use it when the user asks to create,
+  validate, review, install, or troubleshoot a SystemLink example fixture.
+argument-hint: >-
+  Describe the SystemLink workflow you want to inspect, automate, scaffold, or
+  troubleshoot.
+---
+
+# SystemLink CLI
+
+Use this skill when the task is primarily about `slcli` commands or a
+SystemLink resource workflow that should be driven from the CLI.
+
+## When to use it
+
+- Querying or managing SystemLink resources through `slcli`
+- Looking up exact command syntax, flags, or JSON output patterns
+- Building command sequences for analysis, provisioning, packaging, or cleanup
+- Creating, validating, or reviewing `slcli example` fixture YAML
+- Troubleshooting CLI behavior, platform gating, or command selection
+
+## Reference docs
+
+Load only what the current task needs.
+
+| Topic | File | When to load |
+| --- | --- | --- |
+| CLI command reference | [commands.md](./references/commands.md) | Looking up command syntax, options, or examples |
+| Example fixture authoring | [example-authoring.md](./references/example-authoring.md) | Creating or reviewing `config.yaml`, resource references, file-backed fixtures, or validation behavior |
+| Datasheet-to-spec workflow | [datasheet-workflow.md](./references/datasheet-workflow.md) | Importing specifications from PDF, CSV, or structured text |
+| Minimal spec import payload | [import-specs.min.json](./references/import-specs.min.json) | Need a bundled create-compatible starter payload or conditions |
+| Spec import helper | [spec_import_helper.py](./scripts/spec_import_helper.py) | Scaffold or validate a datasheet spec import payload |
+| Filtering guide | [filtering.md](./references/filtering.md) | Advanced filters, LINQ syntax, and query composition |
+| Analysis recipes | [analysis-recipes.md](./references/analysis-recipes.md) | Multi-step analysis workflows and reporting patterns |
+| Troubleshooting | [troubleshooting.md](./references/troubleshooting.md) | SSL, workspace IDs, encoding, or scripting pitfalls |
+| Notebook workflow | [notebook/overview.md](./references/notebook/overview.md) | Creating notebooks for SystemLink |
+| Webapp workflow | [webapp/overview.md](./references/webapp/overview.md) | Hosted Angular webapp scaffolding and deployment |
+| Python test workflow | [python-test/overview.md](./references/python-test/overview.md) | Python test app structure and deployment |
+| Job debugging | [job-debugging/overview.md](./references/job-debugging/overview.md) | Salt job triage and recovery |
+| NI package files | [nipkg/overview.md](./references/nipkg/overview.md) | File-package assembly and `nipkg pack` guidance |
+
+## Default approach
+
+1. At the start of troubleshooting or a substantial `slcli` workflow, run the
+  update preflight once per session:
+
+  ```bash
+  slcli version check
+  slcli skill check --client CLIENT --scope SCOPE
+  ```
+
+  Set `CLIENT` and `SCOPE` to the active skill installation, or use
+  `--directory PATH` for a custom skills directory. If the CLI is outdated,
+  recommend the update command printed by `version check`. If the skill is
+  missing, unversioned, or outdated, recommend `slcli skill install` with the
+  same target and `--force`. Ask before running either update because they
+  modify the user's environment. A failed or unavailable check is advisory:
+  report it briefly and continue the requested workflow unless version skew
+  is the likely cause.
+2. Prefer long-form flags in generated commands.
+3. Use `--format json` when the result will be filtered, transformed, or piped
+   into other tools.
+4. Use `--summary --group-by` for aggregation before fetching large raw result sets.
+5. Use convenience filters first, then fall back to `--filter` with `--substitution` for complex queries.
+6. Stay scoped to the user’s requested resource or workflow.
+7. Load deeper references only when the command surface alone is not enough.
+8. For example authoring or review, load `example-authoring.md` before proposing YAML.
+9. Prefer workspace IDs over names in scripted workflows when an endpoint is strict about identity.
+10. Use `make_api_request` from `slcli.utils` for helper scripts so auth, SSL, and error handling stay consistent.
+11. For datasheet imports, default to autonomy when the product or workspace can be resolved unambiguously.
+
+## Common command groups
+
+| Group | Purpose | Key subcommands |
+| --- | --- | --- |
+| `testmonitor` | Test results and products | `result list/get`, `product list/create/update` |
+| `alarm` | Alarm monitoring and lifecycle actions | `list`, `get`, `acknowledge`, `force-clear`, `delete`, `transition`, `monitor` |
+| `spec` | Specifications | `list`, `query`, `get`, `create`, `import`, `export` |
+| `asset` | Assets and calibration | `list`, `get`, `summary`, `calibration` |
+| `system` | System fleet | `list`, `get`, `compare`, `summary`, `job` |
+| `tag` | Tag read/write | `list`, `get-value`, `set-value`, `create` |
+| `routine` | Event-action routines | `list`, `create`, `enable/disable` |
+| `comment` | Resource comments | `list`, `add`, `update`, `delete` |
+| `workitem` | Work items and workflows | `list`, `create`, `schedule`, `template`, `workflow` |
+| `file` | File management | `list`, `upload`, `download`, `query`, `watch` |
+| `notebook` | Jupyter notebooks | `manage list/create`, `execute start/sync` |
+| `feed` | Package feeds | `list`, `create`, `package upload` |
+| `customfield` | Dynamic form fields | `list`, `create`, `export`, `edit` |
+| `template` | Test plan templates | `list`, `import`, `export` |
+| `webapp` | Web applications | `new`, `pack`, `publish`, `list` |
+| `config` | Connection profiles | `list`, `use`, `add`, `delete` |
+| `user` | User management | `list`, `get`, `create`, `update` |
+| `auth` | Authorization policies | `policy list/create`, `template list` |
+| `workspace` | Workspaces | `list`, `get` |
+| `version` | CLI update hygiene | `check` |
+| `skill` | AI skill installation | `install`, `check` |
+| `example` | Demo provisioning | `list`, `install`, `delete` |
+
+Example package fixtures are declared as `package` resources after a `feed`
+resource. Use `source.type: dummy` for deterministic packages, `file` for a
+fixture-relative `.nipkg`, or `repository` for an explicit HTTPS package URL.
+The repository catalog can identify packages and feeds, but package bytes must
+come from a direct package URL or an existing feed download path.
+
+## Mandatory scope resolution
+
+Before the first resource query, resolve the profile and workspace separately.
+Treat a workspace supplied by the user as a workspace identifier, never as a
+profile name. Match it exactly against either the workspace name or UUID.
+
+1. Run `slcli config list --format json` and select profiles whose `workspace`
+  field matches the requested workspace name. If the user supplied a UUID,
+  probe configured profiles sequentially instead. Do not infer a profile from
+  a similar name such as `demo-fred` or `fred-roaster`.
+2. Use the global `--profile NAME` override on every command. The option goes
+  before the command group, for example:
+
+  ```bash
+  slcli --profile PROFILE_NAME workspace list --format json
+  ```
+
+  This preserves the user's global active profile.
+3. If several profiles match, probe them sequentially with
+  `slcli --profile NAME info --skip-health --format json`. Continue past a
+  missing credential, unavailable endpoint, or permission error. Confirm the
+  selected candidate with one read-only workspace query before issuing the
+  actual resource query. Do not fan out the same query across candidates.
+4. Use the first authorized candidate. Ask the user only when several
+  candidates are authorized and the choice could change the answer.
+5. With the selected profile, run `workspace list --format json` and resolve
+  the requested workspace by exact name or UUID. Carry both the display name
+  and UUID, but use the UUID for subsequent queries when the command accepts
+  it.
+
+When reading `slcli info --format json`, use `active_profile_name` as the
+effective profile after CLI or environment overrides. `current_profile` is the
+persisted config pointer and may differ. Use `api_url_source` to confirm where
+the effective endpoint came from; never use `current_profile` alone to decide
+which profile served a query.
+
+## Mandatory non-interactive webapp deployment protocol
+
+For every webapp creation, publish, redeploy, or update task, load
+[deployment.md](./references/webapp/deployment.md) and follow its ordered
+protocol. Do not build or upload an artifact until the deployment target has
+been resolved. The protocol is non-interactive: use JSON output and bounded
+inventory commands, and do not rely on table pagination or terminal prompts.
+
+1. Discover the installed command surface before composing commands:
+  ```bash
+  slcli config list --format json
+  slcli webapp publish -h
+  slcli webapp list -h
+  ```
+  Installed `--help` wins over this skill and its references. Confirm every
+  option on the installed CLI; `webapp publish` currently has `--id`, `--name`,
+  and `--workspace`, while `webapp list` has bounded JSON output and `-f`.
+  Prefer long options in generated commands after confirming they exist.
+2. Resolve the effective profile and target workspace separately. Probe a
+  candidate with `info --skip-health --format json`, resolve the workspace
+  display name to its UUID with `workspace list --format json`, and carry the
+  UUID into every later command. Never use a similar profile name as a
+  substitute for workspace identity.
+3. Resolve the exact webapp target before building or uploading. Use a
+  bounded, filtered, non-interactive inventory, for example:
+  ```bash
+  slcli --profile PROFILE webapp list \
+    --workspace WORKSPACE_ID --filter "Coffee Tasting" \
+    --take 10 --format json
+  ```
+  The server-side `--filter` is a substring filter, so compare returned names
+  locally. One exact name match means update that webapp with its returned ID
+  by default. Multiple exact matches are ambiguous and require a selected ID.
+  No exact match means report that a new resource would be created and obtain
+  explicit confirmation or an explicit create instruction before using
+  `--name`; never create a duplicate as an implicit fallback.
+4. Inspect the project contract before running its dev server or production
+  build. Read `package.json` and `angular.json`; do not append `--host` when
+  the package script already supplies it. Remove or correct legacy Angular
+  options such as `buildOptimizer` and `vendorChunk` when they make `ng serve`
+  reject the configuration. Run the production build, detect its actual
+  output directory, and verify the hosted routing, CSP, authentication, and
+  service/workspace contract. The Test Monitor results service prefix is
+  `/nitest/v2/query-results`, not `/nitestmonitor/v2/query-results`; do not
+  hardcode `workspace=Default` when the target workspace was resolved.
+5. Publish only after steps 1-4 pass. Pass the resolved workspace for a new
+  webapp, or the exact existing webapp ID for an update. Capture the returned
+  webapp ID, published URL, and publish timestamp in the task record.
+6. Validate at three levels: deployment metadata with `webapp get`, an
+  authenticated CLI query for the target workspace and required resources,
+  and an authenticated browser check of the hosted URL. A reachable URL is
+  not proof of an authenticated app. If the browser redirects to login or
+  returns 401, report exactly: `deployment reachable, interactive hosted
+  validation pending.`
+
+## Product lookup and overview defaults
+
+For product discovery, use this order:
+
+1. Try an exact or likely part number with `testmonitor product list
+  --part-number`.
+2. Try the name and family convenience filters.
+3. If a convenience filter returns `[]`, treat that as inconclusive. Scan the
+  resolved workspace catalog with a bounded JSON query and match name or part
+  number locally with `jq`.
+4. Fetch the selected product with `testmonitor product get <PRODUCT_ID>`.
+
+For a product overview, fetch the product record and directly linked metadata
+only. Use `--summary` for counts and statuses, and grouped summaries for
+profiles, programs, or other supported dimensions. For result data, use only
+dimensions exposed by the command, such as `status` and `programName`. Fetch
+only the latest 5 to 10 results, projecting relevant fields with `jq`. Fetch
+full result details only for a specific run or failure. Record an explicit UTC
+`as of` time and treat counts from separate live queries as separate
+observations.

{systemlink_cli-1.27.1 → systemlink_cli-1.27.3}/slcli/skills/slcli/references/analysis-recipes.md

@@ -17,10 +17,94 @@ Each recipe maps to a real-world scenario and shows the exact commands needed.
 - [Recipe 9: Product family workload distribution](#recipe-9-product-family-workload-distribution)
 - [Recipe 10: Environmental condition failure patterns](#recipe-10-environmental-condition-failure-patterns)
 - [Recipe 11: Create and schedule a work item on a specific fixture/slot and system](#recipe-11-create-and-schedule-a-work-item-on-a-specific-fixtureslot-and-system)
+- [Product discovery and overview](#product-discovery-and-overview)
 - [General tips](#general-tips)
 
 ---
 
+## Product discovery and overview
+
+**Question:** Tell me about a product in a specific workspace without
+producing an oversized, inconsistent report.
+
+**Prerequisite:** Complete the mandatory profile and workspace resolution in
+the main `slcli` skill. Set `PROFILE` to the selected profile and
+`WORKSPACE_ID` to the resolved workspace UUID. Capture the observation time
+before querying live data:
+
+```bash
+PROFILE="<PROFILE_NAME>"
+WORKSPACE_ID="<WORKSPACE_UUID>"
+AS_OF="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+printf 'As of %s\n' "$AS_OF"
+```
+
+**Lookup order:**
+
+```bash
+# 1. Exact or likely part number
+slcli --profile "$PROFILE" testmonitor product list \
+  --workspace "$WORKSPACE_ID" --part-number "<PART_NUMBER>" \
+  --format json --take 25
+
+# 2. Name or family convenience filters, when the part-number lookup is empty
+slcli --profile "$PROFILE" testmonitor product list \
+  --workspace "$WORKSPACE_ID" --name "<PRODUCT_NAME>" \
+  --format json --take 25
+slcli --profile "$PROFILE" testmonitor product list \
+  --workspace "$WORKSPACE_ID" --family "<FAMILY>" \
+  --format json --take 25
+
+# 3. Bounded workspace catalog fallback when convenience filters are empty
+slcli --profile "$PROFILE" testmonitor product list \
+  --workspace "$WORKSPACE_ID" --format json --take 100 |
+  jq --arg name "<PRODUCT_NAME>" --arg part "<PART_NUMBER>" '
+    [ .[] | select(
+        (($name != "") and ((.name // "" | ascii_downcase) | contains($name | ascii_downcase)))
+        or (($part != "") and ((.partNumber // "" | ascii_downcase) | contains($part | ascii_downcase)))
+      ) | {id, name, partNumber, family, workspace} ]'
+```
+
+An empty result from a name or family filter does not prove that the product is
+absent. Increase the bounded catalog limit only deliberately, and project the
+candidate fields in `jq` before displaying them. Fetch the selected record only
+after identifying its ID:
+
+```bash
+slcli --profile "$PROFILE" testmonitor product get <PRODUCT_ID> --format json
+```
+
+**Overview budget:**
+
+```bash
+# Directly linked metadata, only when relevant to the question
+slcli --profile "$PROFILE" spec list --product <PRODUCT_ID> --format json
+
+# Compact counts and status breakdown
+slcli --profile "$PROFILE" testmonitor result list \
+  --part-number "<PART_NUMBER>" --summary --group-by status \
+  --format json
+
+# Grouped program summary
+slcli --profile "$PROFILE" testmonitor result list \
+  --part-number "<PART_NUMBER>" --summary --group-by programName \
+  --format json
+
+# Latest 5 to 10 results, projected to relevant fields
+slcli --profile "$PROFILE" testmonitor result list \
+  --part-number "<PART_NUMBER>" --order-by STARTED_AT --descending \
+  --take 10 --format json |
+  jq '[.[] | {id, status: .status.statusType, startedAt, programName,
+               partNumber, serialNumber}]'
+```
+
+Use `testmonitor result get <RESULT_ID> --include-steps --format json` only
+when the user asks about a particular run or failure. Counts from separate
+commands are not one atomic snapshot; report the `as of` time and call out
+live-data changes when totals do not agree.
+
+---
+
 ## Recipe 1: Operator failure rate analysis
 
 **Question:** Which operators have the highest failure rates and what should they
@@ -482,8 +566,9 @@ slcli workitem schedule wi-12345 \
 - **Start with `--summary`** to understand data shape before fetching raw records.
 - **Use `--group-by`** with `--summary` for aggregation: `status`, `programName`,
   `serialNumber`, `operator`, `hostName`, `systemId`.
-- **Chain with `jq`** for complex transformations — always use `-f json`.
-- **Use `--take` wisely** — start small (100-500), increase if needed.
+- **Chain with `jq`** for complex transformations — always use `--format json`.
+- **Use `--take` wisely** — start with 5-10 for recent detail and a bounded
+  catalog query for discovery; increase only when the question requires it.
 - **For rate calculations**, query total count and filtered count separately, then divide.
 - **Use `--order-by TOTAL_TIME_IN_SECONDS --descending`** to find slowest tests quickly.
 - **Asset `--connected` flag** limits to assets in currently connected systems.