cortexapps-cli 1.37.0__tar.gz → 1.39.0__tar.gz

{cortexapps_cli-1.37.0 → cortexapps_cli-1.39.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexapps-cli
-Version: 1.37.0
+Version: 1.39.0
 Summary: Command Line Interface for cortexapps
 License: MIT
 License-File: LICENSE

{cortexapps_cli-1.37.0 → cortexapps_cli-1.39.0}/cortexapps_cli/commands/solutions.py

@@ -568,7 +568,84 @@ def _apply_hyperlinks(line: str, entity_tags: set[str], ui_url: str) -> str:
     return "".join(parts)
 
 
-def _show_diagram(readme: str, entity_tags: set[str] | None = None, ui_url: str = "https://app.getcortexapp.com") -> None:
+_GITHUB_BLOB = "https://github.com/cortexapps/cli/blob/main/cortexapps_cli/solutions"
+
+
+def _parse_tf_tags_by_type(solution_dir: Path) -> tuple[set[str], set[str]]:
+    """Scan *.tf files under _templates/<solution>/ and return (entity_tags, scorecard_tags)."""
+    entity_tags: set[str] = set()
+    scorecard_tags: set[str] = set()
+    templates = next(
+        (d for d in (solution_dir / "_templates").iterdir() if d.is_dir() and not d.name.endswith("-delta")),
+        None,
+    ) if (solution_dir / "_templates").exists() else None
+    if templates is None:
+        return entity_tags, scorecard_tags
+    for tf in templates.glob("*.tf"):
+        current_type: str | None = None
+        depth = 0
+        for line in tf.read_text(encoding="utf-8").split("\n"):
+            m = re.match(r'\s*resource\s+"(cortex_\w+)"\s+"[^"]+"\s*\{', line)
+            if m:
+                current_type = m.group(1)
+                depth = 1
+                continue
+            if current_type:
+                depth += line.count("{") - line.count("}")
+                if depth <= 0:
+                    current_type = None
+                    depth = 0
+                    continue
+                tm = re.search(r'\btag\s*=\s*"([^"]+)"', line)
+                if tm:
+                    if current_type == "cortex_catalog_entity":
+                        entity_tags.add(tm.group(1))
+                    elif current_type == "cortex_scorecard":
+                        scorecard_tags.add(tm.group(1))
+    return entity_tags, scorecard_tags
+
+
+def _extract_tf_entity_tags(solution_dir: Path) -> set[str]:
+    """Return only cortex_catalog_entity tags from .tf template files."""
+    entity_tags, _ = _parse_tf_tags_by_type(solution_dir)
+    return entity_tags
+
+
+
+def _apply_file_hyperlinks(line: str, solution_tag: str) -> str:
+    """Replace bare filenames in the diagram with OSC 8 links to GitHub blob URLs."""
+    base = f"{_GITHUB_BLOB}/{solution_tag}/_templates/{solution_tag}"
+    parts = []
+    i = 0
+    while i < len(line):
+        # Look for a word boundary start: not alphanumeric/hyphen/dot before current pos
+        for filename in sorted(
+            (f for f in [
+                "teams.tf", "ecommerce.tf", "supply-chain.tf", "scorecards.tf",
+                "provider.tf", "variables.tf", "terraform.tfvars",
+            ] if line.find(f, i) == i),
+            key=len, reverse=True,
+        ):
+            after = i + len(filename)
+            # Ensure word boundary after: next char must not be alphanumeric
+            if after < len(line) and (line[after].isalnum() or line[after] in "-_."):
+                continue
+            parts.append(_osc8(f"{base}/{filename}", filename))
+            i = after
+            break
+        else:
+            parts.append(line[i])
+            i += 1
+    return "".join(parts)
+
+
+
+def _show_diagram(
+    readme: str,
+    entity_tags: set[str] | None = None,
+    ui_url: str = "https://app.getcortexapp.com",
+    solution_tag: str = "",
+) -> None:
     block = _extract_first_codeblock(readme)
     if not block:
         return
@@ -577,23 +654,26 @@ def _show_diagram(readme: str, entity_tags: set[str] | None = None, ui_url: str
 
     print()
     for line in block.split("\n"):
-        if entity_tags and links_supported:
-            line = _apply_hyperlinks(line, entity_tags, ui_url)
+        if links_supported:
+            if entity_tags:
+                line = _apply_hyperlinks(line, entity_tags, ui_url)
+            if solution_tag:
+                line = _apply_file_hyperlinks(line, solution_tag)
         # Use print() not console.print(): Rich counts OSC 8 escape bytes as
         # visible characters, shifting ASCII art alignment.
         print(f"  {line}")
 
     if entity_tags and not links_supported:
-        diagram_tags = sorted(
+        entity_rows = sorted(
             (tag for tag in entity_tags if tag in block),
             key=lambda t: t.lower(),
         )
-        if diagram_tags:
+        if entity_rows:
             print()
             table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2, 0, 0))
             table.add_column("Entity")
             table.add_column("URL")
-            for tag in diagram_tags:
+            for tag in entity_rows:
                 table.add_row(tag, f"{ui_url}/admin/resources?tag={tag}")
             console.print(table)
 
@@ -612,18 +692,21 @@ def _post_install_menu(
     import_report: str = "",
     entity_tags: set[str] | None = None,
     ui_url: str = "https://app.getcortexapp.com",
+    solution_tag: str = "",
 ) -> None:
     options = [
         ("1", "Data Model"),
         ("2", "Next steps"),
-        ("3", "Import report"),
-        ("4", "Exit"),
     ]
     actions = {
-        "1": lambda: _show_diagram(readme, entity_tags=entity_tags, ui_url=ui_url),
+        "1": lambda: _show_diagram(readme, entity_tags=entity_tags, ui_url=ui_url, solution_tag=solution_tag),
         "2": lambda: _show_next_steps(readme),
-        "3": lambda: (console.print(), typer.echo(import_report)),
     }
+    if import_report:
+        options.append(("3", "Import report"))
+        actions["3"] = lambda: (console.print(), typer.echo(import_report))
+    exit_key = str(len(options) + 1)
+    options.append((exit_key, "Exit"))
 
     while True:
         console.print()
@@ -634,7 +717,7 @@ def _post_install_menu(
 
         choice = Prompt.ask("Choice", choices=[k for k, _ in options], show_choices=False)
 
-        if choice == "4":
+        if choice == exit_key:
             break
         actions[choice]()
 
@@ -731,9 +814,23 @@ def install(
                     with as_file(root / solution) as sp:
                         resources = _collect_solution_resources(sp)
                 entity_tags = set(resources.get("catalog", []))
+                if solutions_dir:
+                    entity_tags |= _extract_tf_entity_tags(root / solution)
+                else:
+                    with as_file(root / solution) as sp:
+                        entity_tags |= _extract_tf_entity_tags(sp)
             except Exception:
                 pass
-            _post_install_menu(readme, import_report=output, entity_tags=entity_tags, ui_url=ui_url)
+            has_import_results = bool(
+                total_match and (int(total_match.group(1)) > 0 or int(total_match.group(2)) > 0)
+            )
+            _post_install_menu(
+                readme,
+                import_report=output if has_import_results else "",
+                entity_tags=entity_tags,
+                ui_url=ui_url,
+                solution_tag=solution,
+            )
 
 
 @app.command(name="post-install")

{cortexapps_cli-1.37.0 → cortexapps_cli-1.39.0}/cortexapps_cli/solutions/harness-deploy/setup.py

@@ -231,7 +231,7 @@ class HarnessDeploySetup(SolutionSetup):
         base_url = self._answers["cortex_base_url"].rstrip("/")
         app_url = base_url.replace("api.", "app.", 1) if "api." in base_url else base_url
         entity_tag = self._answers["entity_tag"]
-        cortex_url = f"{app_url}/admin/resources?tag={entity_tag}"  # /admin/resources is the correct URL path (entity terminology in UI)
+        cortex_url = f"{app_url}/admin/resources?tag={entity_tag}"
 
         harness_pipeline_url = (
             f"{self._harness_base()}/ng/account/{self._harness_account()}"

{cortexapps_cli-1.37.0 → cortexapps_cli-1.39.0}/cortexapps_cli/solutions/monorepo/README.md

@@ -1,6 +1,6 @@
 ---
 name: Monorepo
-description: Model a real monorepo in Cortex — five Cortex services mapped to subdirectories of a single public GitHub repo, each scoped by basePath.
+description: Model a real monorepo in Cortex — five Cortex services mapped to subdirectories of a single public GitHub repo, each scoped by basepath.
 ---
 
 # Monorepo
@@ -62,7 +62,7 @@ info:
     github:
       alias: cortex-cli        # only needed with multiple GitHub integrations, and your repo isn't under the default
       repository: cortexapps/cli
-      basePath: cortexapps_cli/solutions/monorepo/services/cli-core
+      basepath: cortexapps_cli/solutions/monorepo/services/cli-core
 ```
 
 All five entities are tagged with the group `monorepo-demo` for easy catalog filtering.
@@ -71,7 +71,7 @@ All five entities are tagged with the group `monorepo-demo` for easy catalog fil
 
 **5 service entities** (group: `monorepo-demo`)
 
-| Tag | basePath | Description |
+| Tag | basepath | Description |
 |---|---|---|
 | `monorepo-demo-cli-core` | `services/cli-core` | Core CLI — Typer app, HTTP client, config, utils |
 | `monorepo-demo-cli-commands` | `services/cli-commands` | Command implementations per Cortex resource |
@@ -79,10 +79,10 @@ All five entities are tagged with the group `monorepo-demo` for easy catalog fil
 | `monorepo-demo-cli-tests` | `services/cli-tests` | Integration test suite against live Cortex API |
 | `monorepo-demo-cli-docker` | `services/cli-docker` | Container infra — published `cortexapp/cli` image |
 
-> Full basePaths are prefixed with `cortexapps_cli/solutions/monorepo/` — shortened above for readability.
+> Full basepaths are prefixed with `cortexapps_cli/solutions/monorepo/` — shortened above for readability.
 
 **1 scorecard** — `monorepo-component-health` — Bronze/Silver/Gold:
-- Bronze: has description + git configured with basePath
+- Bronze: has description + git configured with basepath
 - Silver: belongs to at least one group
 - Gold: verified within 90 days
 
@@ -161,15 +161,15 @@ GitOps syncs automatically on each push to the repo. To trigger a manual sync wi
 3. Select **GitHub**
 4. Follow the prompts to select the `cortexapps/cli` repository
 
-Cortex will find the `cortex.yaml` files in each subdirectory and recreate the deleted entities exactly as defined — group, git basePath, description, and all.
+Cortex will find the `cortex.yaml` files in each subdirectory and recreate the deleted entities exactly as defined — group, git basepath, description, and all.
 
 ## Adapting for Your Own Monorepo
 
 1. Add a `cortex.yaml` to each component subdirectory in your repo
-2. Set `x-cortex-git.github.repository` and `basePath` for each component
+2. Set `x-cortex-git.github.repository` and `basepath` for each component
 3. Add `x-cortex-git.github.alias` if you have more than one GitHub integration configured and your repo isn't under the default
 4. Add a consistent group tag to all components (e.g. `my-monorepo`)
 5. Add GitOps → your repo in Cortex Settings
 6. Cortex discovers and syncs all components automatically
 
-The `basePath` is what splits one repo into many scoped entities — each service sees only the activity in its own directory.
+The `basepath` is what splits one repo into many scoped entities — each service sees only the activity in its own directory.

{cortexapps_cli-1.37.0 → cortexapps_cli-1.39.0}/cortexapps_cli/solutions/monorepo/catalog/cli-commands.yaml

@@ -10,7 +10,7 @@ info:
     github:
       alias: cortex-cli
       repository: cortexapps/cli
-      basePath: cortexapps_cli/solutions/monorepo/services/cli-commands
+      basepath: cortexapps_cli/solutions/monorepo/services/cli-commands
   x-cortex-link:
     - name: GitHub
       type: repo

{cortexapps_cli-1.37.0 → cortexapps_cli-1.39.0}/cortexapps_cli/solutions/monorepo/catalog/cli-core.yaml

@@ -10,7 +10,7 @@ info:
     github:
       alias: cortex-cli
       repository: cortexapps/cli
-      basePath: cortexapps_cli/solutions/monorepo/services/cli-core
+      basepath: cortexapps_cli/solutions/monorepo/services/cli-core
   x-cortex-link:
     - name: GitHub
       type: repo

{cortexapps_cli-1.37.0 → cortexapps_cli-1.39.0}/cortexapps_cli/solutions/monorepo/catalog/cli-docker.yaml

@@ -10,7 +10,7 @@ info:
     github:
       alias: cortex-cli
       repository: cortexapps/cli
-      basePath: cortexapps_cli/solutions/monorepo/services/cli-docker
+      basepath: cortexapps_cli/solutions/monorepo/services/cli-docker
   x-cortex-link:
     - name: GitHub
       type: repo

{cortexapps_cli-1.37.0 → cortexapps_cli-1.39.0}/cortexapps_cli/solutions/monorepo/catalog/cli-solutions.yaml

@@ -10,7 +10,7 @@ info:
     github:
       alias: cortex-cli
       repository: cortexapps/cli
-      basePath: cortexapps_cli/solutions/monorepo/services/cli-solutions
+      basepath: cortexapps_cli/solutions/monorepo/services/cli-solutions
   x-cortex-link:
     - name: GitHub
       type: repo

{cortexapps_cli-1.37.0 → cortexapps_cli-1.39.0}/cortexapps_cli/solutions/monorepo/catalog/cli-tests.yaml

@@ -10,7 +10,7 @@ info:
     github:
       alias: cortex-cli
       repository: cortexapps/cli
-      basePath: cortexapps_cli/solutions/monorepo/services/cli-tests
+      basepath: cortexapps_cli/solutions/monorepo/services/cli-tests
   x-cortex-link:
     - name: GitHub
       type: repo

{cortexapps_cli-1.37.0 → cortexapps_cli-1.39.0}/cortexapps_cli/solutions/monorepo/services/cli-commands/cortex.yaml

@@ -10,7 +10,7 @@ info:
     github:
       alias: cortex-cli
       repository: cortexapps/cli
-      basePath: cortexapps_cli/solutions/monorepo/services/cli-commands
+      basepath: cortexapps_cli/solutions/monorepo/services/cli-commands
   x-cortex-link:
     - name: GitHub
       type: repo

{cortexapps_cli-1.37.0 → cortexapps_cli-1.39.0}/cortexapps_cli/solutions/monorepo/services/cli-core/cortex.yaml

@@ -10,7 +10,7 @@ info:
     github:
       alias: cortex-cli
       repository: cortexapps/cli
-      basePath: cortexapps_cli/solutions/monorepo/services/cli-core
+      basepath: cortexapps_cli/solutions/monorepo/services/cli-core
   x-cortex-link:
     - name: GitHub
       type: repo

{cortexapps_cli-1.37.0 → cortexapps_cli-1.39.0}/cortexapps_cli/solutions/monorepo/services/cli-docker/cortex.yaml

@@ -10,7 +10,7 @@ info:
     github:
       alias: cortex-cli
       repository: cortexapps/cli
-      basePath: cortexapps_cli/solutions/monorepo/services/cli-docker
+      basepath: cortexapps_cli/solutions/monorepo/services/cli-docker
   x-cortex-link:
     - name: GitHub
       type: repo

{cortexapps_cli-1.37.0 → cortexapps_cli-1.39.0}/cortexapps_cli/solutions/monorepo/services/cli-solutions/cortex.yaml

@@ -10,7 +10,7 @@ info:
     github:
       alias: cortex-cli
       repository: cortexapps/cli
-      basePath: cortexapps_cli/solutions/monorepo/services/cli-solutions
+      basepath: cortexapps_cli/solutions/monorepo/services/cli-solutions
   x-cortex-link:
     - name: GitHub
       type: repo

{cortexapps_cli-1.37.0 → cortexapps_cli-1.39.0}/cortexapps_cli/solutions/monorepo/services/cli-tests/cortex.yaml

@@ -10,7 +10,7 @@ info:
     github:
       alias: cortex-cli
       repository: cortexapps/cli
-      basePath: cortexapps_cli/solutions/monorepo/services/cli-tests
+      basepath: cortexapps_cli/solutions/monorepo/services/cli-tests
   x-cortex-link:
     - name: GitHub
       type: repo

{cortexapps_cli-1.37.0 → cortexapps_cli-1.39.0}/cortexapps_cli/solutions/monorepo/setup.py

@@ -233,7 +233,7 @@ class MonorepoSetup(SolutionSetup):
         print(f"4. Ready to model your own monorepo?")
         print(f"   For each component in your repo:")
         print(f"     a. Add a cortex.yaml to the component's subdirectory")
-        print(f"     b. Set x-cortex-git.github.repository and basePath to match")
+        print(f"     b. Set x-cortex-git.github.repository and basepath to match")
         print(f"     c. Add a consistent group tag (e.g. my-monorepo) to all components")
         print(f"     d. Add x-cortex-git.github.alias if you have more than one GitHub integration configured,")
         print(f"        and your entities aren't represented by the 'default' integration")

cortexapps_cli-1.39.0/cortexapps_cli/solutions/terraform/README.md

@@ -0,0 +1,255 @@
+---
+name: Terraform
+description: Manage your Cortex catalog as code using the Cortex Terraform provider.
+---
+
+# Terraform
+
+The [Cortex Terraform provider](https://github.com/cortexapps/terraform-provider-cortex) lets you define your entire service catalog — teams, services, domains, scorecards — as HCL code in `.tf` files. Changes go through PR review and apply automatically on merge, giving you a fully auditable, GitOps-driven catalog.
+
+## Data Model
+
+```
+  ┌──────────────────────────────────────────────────────┐
+  │                   Terraform Repo                     │
+  │                                                      │
+  │  teams.tf          scorecards.tf                     │
+  │  ecommerce.tf      provider.tf                       │
+  │  supply-chain.tf   variables.tf                      │
+  └─────────────────────────────┬────────────────────────┘
+                                │
+                                │  terraform apply
+                                │
+                                ▼
+  ┌──────────────────────────────────────────────────────┐
+  │                   Cortex Catalog                     │
+  │                                                      │
+  │  Teams                                               │
+  │  ┌────────────────────────────────────────────────┐  │
+  │  │  terraform-demo-team-development               │  │
+  │  │  terraform-demo-team-operations                │  │
+  │  │  terraform-demo-team-security                  │  │
+  │  │  terraform-demo-team-qa                        │  │
+  │  └────────────────────────────────────────────────┘  │
+  │                                                      │
+  │  Domains                                             │
+  │  ┌────────────────────────────────────────────────┐  │
+  │  │  terraform-demo-domain-ecommerce               │  │
+  │  │  terraform-demo-domain-supply-chain            │  │
+  │  └────────────────────────────────────────────────┘  │
+  │                                                      │
+  │  Services                                            │
+  │  ┌────────────────────────────────────────────────┐  │
+  │  │  terraform-demo-phoenix                        │  │
+  │  │  terraform-demo-parts-catalog-api              │  │
+  │  │  terraform-demo-payments-service               │  │
+  │  │  terraform-demo-inventory-service              │  │
+  │  │  terraform-demo-ordering-service               │  │
+  │  │  terraform-demo-shipping-service               │  │
+  │  └────────────────────────────────────────────────┘  │
+  │                                                      │
+  │  Scorecard                                           │
+  │  ┌────────────────────────────────────────────────┐  │
+  │  │  terraform-demo-production-readiness           │  │
+  │  └────────────────────────────────────────────────┘  │
+  └──────────────────────────────────────────────────────┘
+```
+
+## What is HCL?
+
+HCL (HashiCorp Configuration Language) is the declarative language used in `.tf` files. It reads like structured config rather than code:
+
+```hcl
+resource "cortex_catalog_entity" "phoenix" {
+  tag         = "terraform-demo-phoenix"
+  name        = "The Phoenix Project"
+  description = "Main e-commerce monolith for Parts Unlimited."
+
+  owners = [{ name = "terraform-demo-team-development", type = "group", provider = "CORTEX" }]
+
+  git = {
+    github = { repository = "parts-unlimited/phoenix" }
+  }
+}
+```
+
+Terraform reads all `.tf` files in a directory, compares them to the current live state, and applies only what changed.
+
+## Terraform vs. cortex.yaml — two flavors of GitOps
+
+Both approaches keep your catalog in git and apply changes on merge. The difference is where the files live:
+
+| | Terraform | cortex.yaml |
+|---|---|---|
+| **Files live in** | One central infra repo | Each service's own repo |
+| **Managed by** | Platform / infra team | Individual service teams |
+| **Also manages** | AWS, GCP, everything else | Just Cortex catalog |
+| **Apply mechanism** | CI runs `terraform apply` | Cortex git integration polls files |
+
+Neither is better. Platform teams who already manage cloud infrastructure with Terraform often prefer the centralized approach. Dev teams who want catalog config alongside their code prefer cortex.yaml.
+
+## File ownership at scale
+
+Terraform has no requirements on file names — it reads all `.tf` files in a directory and merges them. This means you can split by team or domain ownership:
+
+```
+infra-catalog/
+├── provider.tf          ← platform team
+├── teams.tf             ← platform team
+├── scorecards.tf        ← platform team
+├── ecommerce.tf         ← e-commerce team (domain + services)
+├── supply-chain.tf      ← supply chain team (domain + services)
+└── payments.tf          ← payments team
+```
+
+Each team submits PRs touching only their file. At very large scale (100K+ services), teams use Terraform modules (subdirectories) to organize further — but the ownership model is the same.
+
+## What's Included
+
+This solution installs a demo org for **Parts Unlimited** (from *The Phoenix Project*):
+
+- **4 teams**: Development (Bill's team), IT Operations (Brent's domain), Information Security (John's team), QA
+- **2 domains**: E-Commerce, Supply Chain
+- **6 services**: The Phoenix Project, Parts Catalog API, Payments Service, Inventory Service, Ordering Service, Shipping Service
+- **1 scorecard**: Terraform Demo Production Readiness (Bronze/Silver/Gold)
+
+All services start at **Bronze** — intentionally incomplete so you can see the delta in action.
+
+## Prerequisites
+
+- Terraform >= 1.5 — install at https://developer.hashicorp.com/terraform/install
+- Cortex API key with write access
+
+## Install
+
+```bash
+cortex solutions post-install -s terraform
+```
+
+You'll be asked where to create the working directory (default: `~/parts-unlimited-terraform`). The script will:
+1. Verify Terraform is installed
+2. Copy the `.tf` files to your working directory
+3. Write your credentials to `terraform.tfvars`
+4. Run `terraform init` to download the Cortex provider
+5. Run `terraform apply` to create all entities in Cortex
+
+## After Installing
+
+Terraform created 13 entities in your Cortex catalog: 4 teams, 2 domains, and 6 services — all tagged with the `terraform-demo` group.
+
+**Create a catalog to filter to the demo entities**
+
+1. Go to [Catalogs](https://app.getcortexapp.com/admin/catalogs) → **New Catalog**
+2. Name it **Terraform Demo**
+3. Set the catalog filter:
+   - **Entity type:** `service`
+   - **Advanced options → Groups → Include:** `terraform-demo`
+
+**Open the scorecard**
+
+Open [Scorecards](https://app.getcortexapp.com/admin/scorecards) and find **Terraform Demo Production Readiness** to see all 6 services at Bronze.
+
+### Try the Delta
+
+The delta shows what a real team PR looks like — modify a file, plan, apply, watch the scorecard update.
+
+**Step 1: Copy the delta files into your working directory**
+
+The exact delta file paths were printed when you ran `cortex solutions post-install -s terraform`. Copy the delta files shown there to your working directory.
+
+**Step 2: See what will change**
+
+```bash
+cd ~/parts-unlimited-terraform
+terraform plan
+```
+
+You'll see:
+- `~ cortex_catalog_entity.phoenix` — **update** (adds links, metadata to `terraform-demo-phoenix`)
+- `+ cortex_catalog_entity.notification_service` — **create** (`terraform-demo-notification-service`)
+- `~ cortex_catalog_entity.team_development` — **update** (new member on `terraform-demo-team-development`)
+
+**Step 3: Apply**
+
+```bash
+terraform apply
+```
+
+**Step 4: Check the scorecard**
+
+Open [Scorecards](https://app.getcortexapp.com/admin/scorecards) and find **Terraform Demo Production Readiness** in Cortex. The Phoenix Project should now show **Silver**. Also check that the new **Notification Service** appears in your catalog.
+
+## File Walkthrough
+
+**`provider.tf`** — Declares the `cortexapps/cortex` provider version and reads credentials from variables. This is the only file that changes if you upgrade the provider version.
+
+**`variables.tf`** — Defines `cortex_api_token` (sensitive) and `cortex_base_url`. Values come from `terraform.tfvars` (never committed) or environment variables (`CORTEX_API_TOKEN`, `CORTEX_API_URL`).
+
+**`teams.tf`** — Owned by the platform team. Defines all teams and their members. Changes here require a platform PR.
+
+**`ecommerce.tf`** — Owned by the e-commerce team. Defines the E-Commerce domain and its three services. Changes here — new services, updated descriptions, added links — are the e-commerce team's PR to make.
+
+**`supply-chain.tf`** — Same pattern, owned by the supply chain team.
+
+**`scorecards.tf`** — Owned by the platform team. Defines the Terraform Demo Production Readiness scorecard and its Bronze/Silver/Gold rules.
+
+## Customizing for Your Org
+
+1. Rename entity tags and display names throughout
+2. Replace `parts-unlimited/*` GitHub repos with your actual repos
+3. Add more services: copy any service block from `ecommerce.tf` and adjust the tag, name, and owner
+4. Extend scorecard rules: add rules to `scorecards.tf` with the expression language shown in the [Cortex docs](https://docs.cortex.io/docs/reference/scorecard-rules)
+5. Split into more files as your team grows — Terraform reads them all
+
+## Next Steps: CI/CD Integration
+
+In practice, customers commit their `.tf` files to a repo and let CI handle applies. Here's a minimal GitHub Actions workflow:
+
+```yaml
+# .github/workflows/cortex-catalog.yml
+name: Cortex Catalog
+
+on:
+  pull_request:
+    paths: ['catalog/**']
+  push:
+    branches: [main]
+    paths: ['catalog/**']
+
+jobs:
+  plan:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: hashicorp/setup-terraform@v3
+        with:
+          terraform_version: "~> 1.5"
+      - run: terraform init
+        working-directory: catalog
+        env:
+          TF_VAR_cortex_api_token: ${{ secrets.CORTEX_API_TOKEN }}
+      - run: terraform plan
+        working-directory: catalog
+        env:
+          TF_VAR_cortex_api_token: ${{ secrets.CORTEX_API_TOKEN }}
+
+  apply:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: hashicorp/setup-terraform@v3
+        with:
+          terraform_version: "~> 1.5"
+      - run: terraform init
+        working-directory: catalog
+        env:
+          TF_VAR_cortex_api_token: ${{ secrets.CORTEX_API_TOKEN }}
+      - run: terraform apply -auto-approve
+        working-directory: catalog
+        env:
+          TF_VAR_cortex_api_token: ${{ secrets.CORTEX_API_TOKEN }}
+```
+
+Store `CORTEX_API_TOKEN` as a GitHub Actions secret. Now every PR shows a plan diff as a CI check, and every merge to main applies automatically.