systemlink-cli 1.21.0__tar.gz → 1.22.0__tar.gz

{systemlink_cli-1.21.0 → systemlink_cli-1.22.0}/PKG-INFO

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

{systemlink_cli-1.21.0 → systemlink_cli-1.22.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "systemlink-cli"
-version = "1.21.0"
+version = "1.22.0"
 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.21.0 → systemlink_cli-1.22.0}/slcli/_version.py

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

{systemlink_cli-1.21.0 → systemlink_cli-1.22.0}/slcli/example_click.py

@@ -2,6 +2,7 @@
 
 import json
 import sys
+from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 import click
@@ -281,7 +282,13 @@ def register_example_commands(cli: Any) -> None:
             handle_api_error(exc)
 
     @example.command(name="install")
-    @click.argument("example_name")
+    @click.argument("example_name", required=False)
+    @click.option(
+        "--file",
+        "config_file",
+        type=click.Path(exists=True, dir_okay=False, readable=True, resolve_path=True),
+        help="Path to an example config.yaml; referenced files are relative to its directory.",
+    )
     @click.option("--workspace", "-w", required=True, help="Workspace name or ID for resources")
     @click.option(
         "--format",
@@ -302,7 +309,8 @@ def register_example_commands(cli: Any) -> None:
         help="Path to write provisioning results as JSON for auditing.",
     )
     def install_example(
-        example_name: str,
+        example_name: Optional[str],
+        config_file: Optional[str],
         workspace: Optional[str],
         format: str,
         dry_run: bool,
@@ -311,14 +319,29 @@ def register_example_commands(cli: Any) -> None:
         """Provision all resources defined by an example configuration."""
         try:
             loader = ExampleLoader()
-            config = loader.load_config(example_name)
+            example_dir: Optional[Path] = None
+            if config_file and example_name:
+                raise ValueError("Specify either EXAMPLE_NAME or --file, not both.")
+            if not config_file and not example_name:
+                raise ValueError("Provide an EXAMPLE_NAME or --file path to config.yaml.")
+
+            if config_file:
+                config_path = Path(config_file)
+                config = loader.load_config_file(config_path)
+                example_name = str(config["name"])
+                example_dir = config_path.parent
+            else:
+                config = loader.load_config(example_name or "")
 
             workspace_id = _resolve_workspace_id(get_effective_workspace(workspace))
-            provisioner = ExampleProvisioner(
-                workspace_id=workspace_id,
-                example_name=example_name,
-                dry_run=dry_run,
-            )
+            provisioner_options: Dict[str, Any] = {
+                "workspace_id": workspace_id,
+                "example_name": example_name,
+                "dry_run": dry_run,
+            }
+            if example_dir is not None:
+                provisioner_options["example_dir"] = example_dir
+            provisioner = ExampleProvisioner(**provisioner_options)
 
             results, err = provisioner.provision(config)
             if err:

{systemlink_cli-1.21.0 → systemlink_cli-1.22.0}/slcli/example_loader.py

@@ -105,6 +105,31 @@ class ExampleLoader:
                 f"Example '{example_name}' not found. " f"Config path: {config_path}"
             )
 
+        return self._load_config(config_path, example_name)
+
+    def load_config_file(self, config_file: Path) -> Dict[str, Any]:
+        """Load and validate an example configuration from an arbitrary file.
+
+        Args:
+            config_file: Path to the example's YAML configuration file.
+
+        Returns:
+            Validated config dictionary.
+
+        Raises:
+            FileNotFoundError: If the config file does not exist.
+            ValueError: If config fails validation.
+        """
+        config_path = config_file.expanduser().resolve()
+        if not config_path.exists():
+            raise FileNotFoundError(f"Example config not found: {config_path}")
+        if not config_path.is_file():
+            raise ValueError(f"Example config is not a file: {config_path}")
+
+        return self._load_config(config_path, str(config_path))
+
+    def _load_config(self, config_path: Path, source_name: str) -> Dict[str, Any]:
+        """Load and validate a config at a known path."""
         # Load YAML
         try:
             with open(config_path, "r") as f:
@@ -118,14 +143,14 @@ class ExampleLoader:
         # Validate schema
         errors = self.validate_config(config)
         if errors:
-            msg = f"Config validation failed for '{example_name}':\n"
+            msg = f"Config validation failed for '{source_name}':\n"
             msg += "\n".join(f"  - {e}" for e in errors)
             raise ValueError(msg)
 
         # Validate references
         ref_errors = self._validate_references(config)
         if ref_errors:
-            msg = f"Reference validation failed for '{example_name}':\n"
+            msg = f"Reference validation failed for '{source_name}':\n"
             msg += "\n".join(f"  - {e}" for e in ref_errors)
             raise ValueError(msg)
 
@@ -148,6 +173,10 @@ class ExampleLoader:
         if missing_fields:
             errors.append(f"Missing required fields: {', '.join(sorted(missing_fields))}")
 
+        name = config.get("name")
+        if "name" in config and (not isinstance(name, str) or not name.strip()):
+            errors.append("name must be a non-empty string")
+
         # Check format_version is supported
         version = config.get("format_version")
         if version and version not in self.SUPPORTED_SCHEMA_VERSIONS:

{systemlink_cli-1.21.0 → systemlink_cli-1.22.0}/slcli/example_provisioner.py

@@ -62,6 +62,7 @@ class ExampleProvisioner:
         workspace_id: Optional[str] = None,
         example_name: Optional[str] = None,
         dry_run: bool = False,
+        example_dir: Optional[Path] = None,
     ) -> None:
         """Initialize the provisioner.
 
@@ -69,10 +70,12 @@ class ExampleProvisioner:
             workspace_id: Workspace identifier (ID).
             example_name: Example name for tagging resources.
             dry_run: When True, does not create any resources (SKIPPED).
+            example_dir: Directory containing an externally supplied example config.
         """
         self.workspace_id = workspace_id
         self.example_name = example_name
         self.dry_run = dry_run
+        self.example_dir = example_dir
         self.id_map: Dict[str, str] = {}
         self._test_results_deleted: bool = False
         self._files_deleted: bool = False
@@ -3480,15 +3483,10 @@ class ExampleProvisioner:
         Returns:
             File contents as bytes, or None if not found.
         """
-        from pathlib import Path
-
         try:
-            if self.example_name:
-                # Path relative to slcli/examples/{example_name}/
-                example_dir = Path(__file__).parent / "examples" / self.example_name
-                full_path = example_dir / file_path
-            else:
-                full_path = Path(file_path)
+            full_path = self._resolve_example_file(file_path)
+            if full_path is None:
+                return None
 
             if not full_path.exists():
                 click.echo(
@@ -3518,6 +3516,31 @@ class ExampleProvisioner:
             )
             return None
 
+    def _resolve_example_file(self, file_path: str) -> Optional[Path]:
+        """Resolve a fixture file and contain it when a fixture directory is configured.
+
+        Without a fixture directory, return the path as provided for backwards
+        compatibility with callers that supply their own working-directory context.
+        """
+        if self.example_dir:
+            example_dir = self.example_dir
+        elif self.example_name:
+            example_dir = Path(__file__).parent / "examples" / self.example_name
+        else:
+            return Path(file_path)
+
+        try:
+            resolved_dir = example_dir.resolve()
+            resolved_path = (resolved_dir / file_path).resolve()
+            resolved_path.relative_to(resolved_dir)
+            return resolved_path
+        except (OSError, ValueError):
+            click.echo(
+                f"Warning: File path must remain inside the example directory: {file_path}",
+                err=True,
+            )
+            return None
+
     def _get_notebook_by_name(self, name: str) -> Optional[str]:
         """Look up an example-owned notebook by name and workspace."""
         if not name:
@@ -3566,16 +3589,12 @@ class ExampleProvisioner:
 
         if not name or not file_path:
             return None
-        from pathlib import Path
 
         try:
-            # Resolve file path relative to example directory
-            if self.example_name:
-                # Path relative to slcli/examples/{example_name}/
-                example_dir = Path(__file__).parent / "examples" / self.example_name
-                notebook_file = example_dir / file_path
-            else:
-                notebook_file = Path(file_path)
+            # Resolve file path relative to the example directory
+            notebook_file = self._resolve_example_file(file_path)
+            if notebook_file is None:
+                return None
 
             if not notebook_file.exists():
                 return None

{systemlink_cli-1.21.0 → systemlink_cli-1.22.0}/slcli/examples/README.md

@@ -76,6 +76,12 @@ slcli example install demo-data-2 -w <workspace> --audit-log install-log.json --
 slcli example install demo-data-3 \
   -w <workspace> --format json --audit-log nigel-fixture-manifest.json
 
+# Install an example from any local directory. Paths in config.yaml are
+# resolved relative to the directory containing config.yaml.
+slcli example install \
+  --file ./fixtures/example-resources/config.yaml \
+  --workspace <workspace>
+
 # Delete example resources from a workspace
 slcli example delete demo-data-2 -w <workspace-id> --dry-run
 slcli example delete demo-data-2 -w <workspace>
@@ -85,6 +91,10 @@ slcli example delete demo-data-2 -w <workspace> --audit-log delete-log.json --fo
 
 ## Creating New Examples
 
+For the complete authoring contract, including external fixture directories,
+resource references, file-backed resources, and validation caveats, see the
+[Example Fixture Authoring Guide](../skills/slcli/references/example-authoring.md).
+
 1. Create a new directory in `examples/`:
 
    ```
@@ -93,13 +103,37 @@ slcli example delete demo-data-2 -w <workspace> --audit-log delete-log.json --fo
    └── README.md            # Optional: Setup guide
    ```
 
-2. Create `config.yaml` following the schema in `_schema/schema-v1.0.json`
+2. Create `config.yaml` following the schema in
+  [`_schema/schema-v1.0.json`](_schema/schema-v1.0.json). Use the closest
+  bundled example as the reference for resource-specific `properties`.
 
 3. Test locally:
-   ```bash
-   slcli example info my-example
+  ```bash
+  slcli example install my-example --workspace <workspace> --dry-run
    ```
 
+External fixtures use the same format and do not need to be copied into the
+package:
+
+```text
+fixtures/example-resources/
+├── config.yaml
+├── README.md
+└── product-xyz-specification.csv
+```
+
+```bash
+slcli example install \
+  --file fixtures/example-resources/config.yaml \
+  --workspace <workspace> \
+  --dry-run
+```
+
+Paths in `file_path`, `rows_file`, and `data_file` properties are resolved
+relative to the directory containing `config.yaml`. Only files named by a
+resource are uploaded; a sibling README or data file is not uploaded merely
+because it is present.
+
 ## Configuration Format
 
 All examples use YAML format with the following structure:
@@ -158,9 +192,13 @@ cleanup:
 ## Notes
 
 - Examples are versioned with the `format_version` field (currently 1.0)
-- Resource cleanup is tag-based and order-aware
+- Resource cleanup uses example ownership tags and reverse resource order. The
+  `cleanup` block is descriptive metadata; `example delete` does not currently
+  consume its custom order or confirmation settings.
 - References use `${id_reference}` syntax for interpolation
+- Resources are provisioned in list order, so referenced resources must appear first
 - All resources created by an example are tagged with the example name for safe deletion
+- The JSON Schema is the authoring reference; runtime validation currently checks only a subset of its types and patterns
 - Examples with `install_manifest: true` emit grouped resource actions and a
   `validation.complete` flag when JSON output is requested. Unsupported
   capabilities or failed relationships make the command return a nonzero exit

{systemlink_cli-1.21.0 → systemlink_cli-1.22.0}/slcli/examples/_schema/schema-v1.0.json

@@ -25,6 +25,10 @@
       "type": "string",
       "description": "Human-readable example title"
     },
+    "example_version": {
+      "type": "string",
+      "description": "Fixture data version used in the optional install manifest"
+    },
     "description": {
       "type": "string",
       "description": "Detailed description of what example includes"
@@ -64,6 +68,15 @@
       ],
       "description": "Target workspace name or null for default"
     },
+    "workspace_name": {
+      "type": "string",
+      "description": "Workspace name recorded in the optional install manifest"
+    },
+    "install_manifest": {
+      "type": "boolean",
+      "default": false,
+      "description": "Emit the grouped install manifest when JSON output is requested"
+    },
     "resources": {
       "type": "array",
       "items": {
@@ -79,19 +92,19 @@
           "items": {
             "type": "string"
           },
-          "description": "Resource types to delete in this order"
+          "description": "Descriptive intended deletion order; generic example delete currently reverses the resources list"
         },
         "filter_tags": {
           "type": "array",
           "items": {
             "type": "string"
           },
-          "description": "Only delete resources with these tags"
+          "description": "Tags intended for cleanup filtering"
         },
         "require_confirmation": {
           "type": "boolean",
           "default": true,
-          "description": "Require confirmation before cleanup"
+          "description": "Descriptive confirmation preference; generic example delete does not currently prompt from this field"
         }
       }
     },
@@ -102,6 +115,27 @@
           "type": "boolean",
           "default": true,
           "description": "Workspace must exist before install"
+        },
+        "required_relationships": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Relationships the fixture expects to be queryable after install"
+        },
+        "failed_relationships": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Relationships that failed validation"
+        },
+        "unsupported": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Capabilities intentionally not represented by the fixture"
         }
       }
     },

{systemlink_cli-1.21.0 → systemlink_cli-1.22.0}/slcli/skills/slcli/SKILL.md

@@ -4,7 +4,9 @@ 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, or other SystemLink resource workflows.
+  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.
@@ -20,6 +22,7 @@ SystemLink resource workflow that should be driven from the CLI.
 - 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
@@ -29,6 +32,7 @@ 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 |
@@ -49,9 +53,10 @@ Load only what the current task needs.
 4. Use convenience filters first, then fall back to `--filter` with `--substitution` for complex queries.
 5. Stay scoped to the user’s requested resource or workflow.
 6. Load deeper references only when the command surface alone is not enough.
-7. Prefer workspace IDs over names in scripted workflows when an endpoint is strict about identity.
-8. Use `make_api_request` from `slcli.utils` for helper scripts so auth, SSL, and error handling stay consistent.
-9. For datasheet imports, default to autonomy when the product or workspace can be resolved unambiguously.
+7. For example authoring or review, load `example-authoring.md` before proposing YAML.
+8. Prefer workspace IDs over names in scripted workflows when an endpoint is strict about identity.
+9. Use `make_api_request` from `slcli.utils` for helper scripts so auth, SSL, and error handling stay consistent.
+10. For datasheet imports, default to autonomy when the product or workspace can be resolved unambiguously.
 
 ## Common command groups
 

{systemlink_cli-1.21.0 → systemlink_cli-1.22.0}/slcli/skills/slcli/references/commands.md

@@ -932,5 +932,12 @@ for training, testing, or evaluation.
 slcli example list [-f json]                             # List available examples
 slcli example info <EXAMPLE_ID>                          # Show example details
 slcli example install <EXAMPLE_ID> [--workspace NAME]    # Provision example resources
+slcli example install --file PATH [--workspace NAME]     # Install a local fixture
 slcli example delete <EXAMPLE_ID> [--workspace NAME]     # Remove provisioned resources
 ```
+
+For a local fixture, `PATH` points to its `config.yaml`; referenced files are
+resolved relative to the directory containing that file.
+
+For the YAML contract and authoring workflow, load
+[example-authoring.md](./example-authoring.md).

systemlink_cli-1.22.0/slcli/skills/slcli/references/example-authoring.md

@@ -0,0 +1,193 @@
+# Example Fixture Authoring
+
+Use this guide when creating a SystemLink example for `slcli example install`.
+The machine-readable contract is [schema-v1.0.json](../../../examples/_schema/schema-v1.0.json).
+The schema defines the common YAML envelope; the bundled examples show the
+SystemLink API properties for each resource type.
+
+## Quick Start
+
+An example is a directory containing `config.yaml` and any files referenced by
+that configuration:
+
+```text
+fixtures/example-resources/
+├── config.yaml
+├── README.md
+├── product-xyz-specification.csv
+└── notebooks/
+    └── analysis.ipynb
+```
+
+Install a bundled example by name:
+
+```bash
+slcli example install demo-data-1 \
+  --workspace <workspace> --dry-run
+```
+
+Install an example from any local directory with `--file`:
+
+```bash
+slcli example install \
+  --file fixtures/example-resources/config.yaml \
+  --workspace <workspace> \
+  --dry-run
+```
+
+For `--file` installs, all relative file references are resolved from the
+directory containing `config.yaml`. A README or an unreferenced file is not
+uploaded automatically; add a `file` or `notebook` resource when it should be
+published to SystemLink.
+
+## Configuration Contract
+
+The required top-level fields are:
+
+| Field | Meaning |
+| --- | --- |
+| `format_version` | Schema version. Use the string `"1.0"`. |
+| `name` | Lowercase example slug using letters, numbers, and hyphens. It is also used for ownership tagging. |
+| `title` | Human-readable title. |
+| `resources` | Ordered list of resources to create. |
+
+Common optional fields include `description`, `author`, `created_date`,
+`updated_date`, `example_version`, `tags`, `estimated_setup_time_minutes`,
+`required_systemlink_version`, `target_workspace`, `workspace_name`,
+`install_manifest`, `cleanup`, `validation`, and `post_install`.
+
+Each resource has this envelope:
+
+```yaml
+- type: "location"
+  name: "Production Test Lab"
+  properties:
+    city: "Austin"
+  id_reference: "loc_lab"
+  tags: ["example-resources"]
+```
+
+- `type` selects one of the supported resource handlers.
+- `name` is the resource name sent to SystemLink.
+- `properties` contains fields specific to that resource type.
+- `id_reference` is a local identifier using lowercase letters, numbers, and
+  underscores. Use it in later properties as `${id_reference}`.
+- `tags` is used for organization and cleanup filtering.
+
+Resources are processed in list order. Put a resource before any resource that
+references its ID. References are resolved recursively inside `properties`, but
+only a complete string such as `${loc_lab}` is substituted; embedded text such
+as `location-${loc_lab}` is not substituted.
+
+## Resource Types
+
+The supported `type` values are:
+
+| Type | Typical use | Example |
+| --- | --- | --- |
+| `location` | Physical location hierarchy | [demo-data-1](../../../examples/demo-data-1/config.yaml) |
+| `product` | Product definition and part number | [demo-data-3](../../../examples/demo-data-3/config.yaml) |
+| `system` | Test system or virtual system | [demo-data-3](../../../examples/demo-data-3/config.yaml) |
+| `asset` | Instrument or equipment asset | [demo-data-3](../../../examples/demo-data-3/config.yaml) |
+| `dut` | Device under test | [demo-data-1](../../../examples/demo-data-1/config.yaml) |
+| `testtemplate` | Test plan template | [demo-data-2](../../../examples/demo-data-2/config.yaml) |
+| `workflow` | Work item state machine | [demo-data-1](../../../examples/demo-data-1/config.yaml) |
+| `work_item` | Work item instance | [demo-data-1](../../../examples/demo-data-1/config.yaml) |
+| `work_order` | Work order | [demo-data-1](../../../examples/demo-data-1/config.yaml) |
+| `test_result` | Test Monitor result and optional steps | [demo-data-3](../../../examples/demo-data-3/config.yaml) |
+| `data_table` | DataFrame table and optional rows | [demo-data-3](../../../examples/demo-data-3/config.yaml) |
+| `file` | Supporting file upload | [spec-compliance-notebooks](../../../examples/spec-compliance-notebooks/config.yaml) |
+| `notebook` | Jupyter notebook upload | [spec-compliance-notebooks](../../../examples/spec-compliance-notebooks/config.yaml) |
+| `feed` | Package feed metadata | [demo-data-3](../../../examples/demo-data-3/config.yaml) |
+| `state` | Deployment state metadata | [demo-data-3](../../../examples/demo-data-3/config.yaml) |
+| `tag` | Workspace tag and optional history | [demo-data-3](../../../examples/demo-data-3/config.yaml) |
+| `specification` | Product specification and conditions | [demo-data-3](../../../examples/demo-data-3/config.yaml) |
+| `alarm` | Alarm instance or transition | [demo-data-3](../../../examples/demo-data-3/config.yaml) |
+
+The `properties` object is intentionally resource-specific and open-ended in
+the common schema. Start with the closest bundled example and verify the
+property names against the corresponding `slcli` command or API model.
+
+## File-Backed Resources
+
+These are the file-reference keys consumed by the generic provisioner:
+
+| Resource | Property | Value |
+| --- | --- | --- |
+| `file` | `file_path` | Relative path to bytes to upload. `description`, `content_type`, `keywords`, and `tags` are also supported metadata. |
+| `notebook` | `file_path` | Relative path to an `.ipynb` file. `notebook_interface` selects the notebook interface, for example `File Analysis`. |
+| `data_table` | `rows_file` or `data_file` | Relative path to JSON rows. The JSON may be a list of rows or an object containing `frame.columns` and `frame.data`. |
+
+A data table may use inline `rows` instead of a rows file, but it must not
+define both. Row values are normalized to strings when appended. The configured
+`columns` must match the columns in the rows payload when both are provided.
+
+Example:
+
+```yaml
+- type: "file"
+  name: "product-xyz-specification.csv"
+  properties:
+    file_path: "product-xyz-specification.csv"
+    content_type: "text/csv"
+  id_reference: "file_specification"
+
+- type: "data_table"
+  name: "Overvoltage Results"
+  properties:
+    columns:
+      - name: "timestamp"
+      - name: "value"
+    rows_file: "data/overvoltage-results.json"
+  id_reference: "table_overvoltage"
+```
+
+## Validation And Dry Runs
+
+The JSON Schema is the authoring reference, but the current loader performs a
+smaller runtime validation set. It checks required fields, the supported format
+version, supported resource types, basic resource reference identifiers, and
+undefined `${reference}` values. It does not enforce every JSON Schema type or
+pattern, and `properties` remains API-specific.
+
+Use a dry run before making API calls:
+
+```bash
+slcli example install \
+  --file fixtures/example-resources/config.yaml \
+  --workspace <workspace> \
+  --dry-run \
+  --format json
+```
+
+For a real install, inspect the JSON result when checking automation:
+
+```bash
+slcli example install \
+  --file fixtures/example-resources/config.yaml \
+  --workspace <workspace> \
+  --format json \
+  --audit-log install.json
+```
+
+A successful resource list does not prove that every intended relationship or
+capability was created. If the configuration uses `install_manifest: true`,
+check `validation.complete` and the `unsupported` and `failed_relationships`
+entries in the JSON manifest.
+
+The `cleanup` block is currently descriptive metadata. `slcli example delete`
+uses the example ownership marker and reverses the resource list; it does not
+currently apply a custom cleanup order or confirmation setting from the YAML.
+
+## Authoring Checklist
+
+Before sharing an example:
+
+1. Put `config.yaml` and every referenced file in the fixture directory.
+2. Set a unique lowercase `name` and `format_version: "1.0"`.
+3. Give every resource a unique `id_reference` and place resources in dependency order.
+4. Use the closest bundled fixture as the reference for resource-specific properties.
+5. Add explicit `file` or `notebook` resources for files that should be uploaded.
+6. Run the external-file dry run and inspect JSON output for failed resources.
+7. Add a README with the workspace prerequisites, expected resources, and post-install steps.
+8. Add an `install_manifest` and `validation` section when the fixture has known limitations.