Merge pull request #3496 from muchzill4/topo-projects

Update Topo Learning Paths for Project terminology and current CLI

Author: pareenaverma

…create-your-own-topo-templates/_index.md …m/create-your-own-topo-project/_index.mdcontent/learning-paths/cross-platform/create-your-own-topo-templates/_index.md renamed to content/learning-paths/cross-platform/create-your-own-topo-project/_index.md content/learning-paths/cross-platform/create-your-own-topo-templates/_index.md renamed to content/learning-paths/cross-platform/create-your-own-topo-project/_index.md

@@ -1,18 +1,21 @@
 ---
-title: Create and deploy a custom Topo Template
+title: Create and deploy a custom Topo Project
 
-description: Understand how to create and modify Topo Templates, allowing you to deploy your projects as containerized workloads to Arm-based Linux targets over SSH.
+aliases:
+    - /learning-paths/cross-platform/create-your-own-topo-templates/
+
+description: Understand how to create and modify Topo Projects, allowing you to deploy your projects as containerized workloads to Arm-based Linux targets over SSH.
 
 minutes_to_complete: 30
 
-who_is_this_for: This is an introductory topic for embedded, edge, and cloud software developers who want to create their own Topo Templates projects to be natively deployed with Topo.
+who_is_this_for: This is an introductory topic for embedded, edge, and cloud software developers who want to create their own Topo Projects to be natively deployed with Topo.
 
 learning_objectives:
-    - Explain the purpose and structure of a Topo Template
-    - Clone and deploy an existing Topo Template and modify it by adding new clone-time arguments
-    - Create a new Topo Template from a Docker Compose project
-    - Add x-topo metadata for configurable arguments, deployment guidance, and hardware requirements
-    - Locate and install Agent Skills to assist with creating and reviewing Topo Templates
+    - Explain the purpose and structure of a Topo Project
+    - Clone and deploy an existing Topo Project and modify it by adding new clone-time parameters
+    - Create a new Topo Project from a Docker Compose project
+    - Add x-topo metadata for configurable parameters, deployment guidance, and hardware requirements
+    - Locate and install Agent Skills to assist with creating and reviewing Topo Projects
 
 prerequisites:
     - Completion of the [Deploy containerized workloads to Arm-based Linux targets with Topo](/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/) Learning Path.
@@ -36,39 +39,39 @@ generated_summary_faq:
   faq_generated_at: '2026-07-02T19:10:34Z'
   faq_source_hash: 280ddbaed118073072407c7e43c743f4d090e153201401deeec4648f9fb0c4ba
   summary: >-
-    You'll author and deploy Topo Templates to Arm-based
-    Linux targets over SSH. First, you'll clone and run a starter template to confirm your setup, then edit
-    its `compose.yaml` to add `x-topo` arguments that make the greeting emoji configurable at clone
-    time. Next, you'll create a new template from an empty directory that serves a simple web page
-    with configurable text and color while learning the core pieces of a template: standard Compose
+    You'll author and deploy Topo Projects to Arm-based
+    Linux targets over SSH. First, you'll clone and run a starter project to confirm your setup, then edit
+    its `compose.yaml` to add `x-topo.parameters` entries that make the greeting emoji configurable at clone
+    time. Next, you'll create a new project from an empty directory that serves a simple web page
+    with configurable text and color while learning the core pieces of a project: standard Compose
     services, `x-topo` metadata, and build arguments for Arm Linux targets. You'll also see
     where to find optional Agent Skills to assist with creating or converting projects, and how
     to recognize a successful deployment by observing the configured behavior on the target.
   faqs:
-  - question: What should I see after running `topo clone` on the Hello World template?
+  - question: What should I see after running `topo clone` on the Hello World project?
     answer: >-
       You should see a new directory at the path you provided (for example, `~/topo-welcome`) and
       clone output that includes lines like `Copy files` and `Cloning into ...`. After cloning,
-      the template’s services can be deployed to the Arm-based Linux target as shown in the steps.
+      the project’s services can be deployed to the Arm-based Linux target as shown in the steps.
   - question: Where do I add a new clone-time argument such as a greeting emoji?
     answer: >-
-      Add it under the `x-topo` args section in `compose.yaml`, alongside the existing `GREETING_NAME`
-      argument. Define the argument name and metadata there so Topo can surface it during cloning.
+      Add it under the `x-topo` parameters section in `compose.yaml`, alongside the existing `GREETING_NAME`
+      parameter. Define the parameter name and metadata there so Topo can surface it during cloning.
   - question: How do I confirm that my new argument is being used?
     answer: >-
-      Clone and deploy the updated template, then check the running service’s behavior for your
+      Clone and deploy the updated project, then check the running service’s behavior for your
       change. For example, the Hello World greeting should include the emoji you configured, or
       the sample webpage should reflect your chosen text and color.
-  - question: What are the essential parts of a minimal Topo Template I create from scratch?
+  - question: What are the essential parts of a minimal Topo Project I create from scratch?
     answer: >-
-      Include a `compose.yaml` with standard Compose services, an `x-topo` metadata block, and build
-      arguments exposed as Topo clone-time parameters. The container image should be built for
+      Include a `compose.yaml` with standard Compose services, an `x-topo` metadata block, and project
+      parameters wired to Docker build arguments when needed. The container image should be built for
       Arm Linux targets.
-  - question: When should I use Agent Skills, and which ones are available for templates?
+  - question: When should I use Agent Skills, and which ones are available for projects?
     answer: >-
       Use Agent Skills as optional aids when you want help creating or converting a project into
-      a Topo Template. The specification provides `topo-template-context` for reference about `x-topo`
-      and CLI behavior and `topo-template-bootstrap` to help convert a repository into a Topo Template.
+      a Topo Project. Topo provides `topo-project-context` for reference about `x-topo`
+      and CLI behavior and `topo-project-bootstrap` to help convert a repository into a Topo Project.
 # END generated_summary_faq
 
 author: Tomas Agustin Gonzalez Orlando
@@ -102,8 +105,8 @@ shared_between:
 
 further_reading:
     - resource:
-        title: Topo Template format
-        link: https://github.com/arm/topo-template-format
+        title: Topo Project specification
+        link: https://github.com/arm/topo/tree/main/docs/project-specification
         type: documentation
     - resource:
         title: Topo repository

…e-your-own-topo-templates/_next-steps.md …ate-your-own-topo-project/_next-steps.mdcontent/learning-paths/cross-platform/create-your-own-topo-templates/_next-steps.md renamed to content/learning-paths/cross-platform/create-your-own-topo-project/_next-steps.md content/learning-paths/cross-platform/create-your-own-topo-templates/_next-steps.md renamed to content/learning-paths/cross-platform/create-your-own-topo-project/_next-steps.md

@@ -0,0 +1,51 @@
+---
+title: Use Agent Skills to author Topo Projects
+description: Install and use Topo Project Agent Skills to help create, review, and refine Topo Projects.
+weight: 6
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Skills for authoring Topo Projects
+
+If you already have a Docker Compose project and want to convert it to a Topo Project, you can do so with an Agent Skill. You can also use a skill to create your own Topo Project from scratch. These skills are optional authoring aids. 
+
+[Topo](https://github.com/arm/topo) currently provides the following skills:
+
+- `topo-project-context`: provides Topo and Topo Project reference context for questions about x-topo metadata, schema, docs, and CLI project behavior.
+- `topo-project-bootstrap`: converts a repository into a Topo Project by adding or improving `compose.yaml` and `x-topo` metadata.
+- `topo-project-lint`: reviews an existing Topo Project for correctness, consistency, and authoring best practices.
+- `topo-project-optimize-deployment`: optimizes feedback loop by measuring and applying the highest-leverage Docker build improvement.
+
+For the most up-to-date list of the available Topo skills, see [Topo Skills](https://github.com/arm/topo/tree/main/skills).
+
+## Install the skills
+
+Install the Topo skills with [npx skills](https://github.com/vercel-labs/skills):
+
+{{% notice Note %}}
+`npx` requires Node.js. If you don't have Node.js installed on your machine, install it before running the following command.
+{{% /notice %}}
+
+```bash
+npx skills add arm/topo
+```
+
+Restart your AI coding agent after installing or updating skills to make sure new skills are loaded for use.
+
+## Use the skills
+
+After installing skills, you can prompt your agent to use a skill.
+
+For example, to create a Topo Project from an existing project:
+
+```text
+Use the topo-project-bootstrap skill to convert this repository into a Topo Project.
+```
+
+## What you've accomplished 
+
+You've now learned how you can install and use Agent Skills to help author Topo Projects.
+
+You can now create, modify, and deploy Topo Projects to Arm-based Linux targets. To find more projects to clone and modify, explore the [Topo Catalog](https://github.com/arm/topo-project-catalog/blob/main/data/catalog.json).

content/learning-paths/cross-platform/create-your-own-topo-project/agent-skills.md

@@ -1,6 +1,6 @@
 ---
-title: Create a new Topo Template from an empty directory
-description: Create a Topo Template from a Docker Compose project with x-topo metadata, clone-time arguments, and an Arm Linux container image.
+title: Create a new Topo Project from an empty directory
+description: Create a Topo Project from a Docker Compose project with x-topo metadata, clone-time parameters, and an Arm Linux container image.
 weight: 5
 
 ### FIXED, DO NOT MODIFY
@@ -9,9 +9,9 @@ layout: learningpathall
 
 ## Create a web page with configurable text and color
 
-You've already cloned and modified an existing Topo Template. In this section, you'll create a new template from an empty directory.
+You've already cloned and modified an existing Topo Project. In this section, you'll create a new project from an empty directory.
 
-The template serves a small web page with configurable text and color, and demonstrates the core parts of a Topo Template:
+The project serves a small web page with configurable text and color, and demonstrates the core parts of a Topo Project:
 
 - A `compose.yaml` file with standard Compose services
 - An `x-topo` metadata block
@@ -20,14 +20,14 @@ The template serves a small web page with configurable text and color, and demon
 
 ### Create the project directory
 
-Create a new directory for the template:
+Create a new directory for the project:
 
 ```bash
 mkdir -p ~/topo-message-card
 cd ~/topo-message-card
 ```
 
-A Topo Template is a normal project directory. At minimum, it needs to contain a `compose.yaml` file. Most Topo Templates also include a `Dockerfile` and application source code.
+A Topo Project is a normal project directory. At minimum, it needs to contain a `compose.yaml` file. Most Topo Projects also include a `Dockerfile` and application source code.
 
 By the end of this section, the directory you created will have the following structure:
 
@@ -108,15 +108,15 @@ FROM nginx:alpine
 COPY src/index.html /usr/share/nginx/html/index.html
 
 ARG CARD_TITLE="Hello from Topo"
-ARG CARD_MESSAGE="This page was created from a Topo Template."
+ARG CARD_MESSAGE="This page was created from a Topo Project."
 ARG ACCENT_COLOR="#0091bd"
 
 RUN sed -i "s|__CARD_TITLE__|${CARD_TITLE}|g" /usr/share/nginx/html/index.html
 RUN sed -i "s|__CARD_MESSAGE__|${CARD_MESSAGE}|g" /usr/share/nginx/html/index.html
 RUN sed -i "s|__ACCENT_COLOR__|${ACCENT_COLOR}|g" /usr/share/nginx/html/index.html
 ```
 
-Topo passes configuration values to Topo Templates through Docker build arguments. The `ARG` lines define the values consumed during the image build.
+Topo passes configuration values to Topo Projects through Docker build arguments. The `ARG` lines define the values consumed during the image build.
 
 `sed` is a command-line text replacement tool. The `sed` commands replace placeholder text in `index.html` during the image build. This way, each cloned project can customize the web page without manually editing the source file.
 
@@ -125,36 +125,35 @@ Topo passes configuration values to Topo Templates through Docker build argument
 Create `compose.yaml` in the `topo-message-card` directory with the following content:
 
 ```yaml
-# yaml-language-server: $schema=https://raw.githubusercontent.com/arm/topo-template-format/refs/heads/main/schema/topo-template-format.json
+# yaml-language-server: $schema=https://raw.githubusercontent.com/arm/topo/refs/heads/main/docs/project-specification/schema/topo-project-specification.json
 services:
   message-card:
     platform: linux/arm64
     build:
       context: .
       args:
         CARD_TITLE: "Hello from Topo"
-        CARD_MESSAGE: "This page was created from a Topo Template."
+        CARD_MESSAGE: "This page was created from a Topo Project."
         ACCENT_COLOR: "#0091bd"
     ports:
       - "8088:80"
 
 x-topo:
   name: "Message Card"
   description: |
-    A minimal web application template that shows a configurable title,
+    A minimal web application project that shows a configurable title,
     message, and accent color.
-  type: "application"
-  deploy_success_message: |
+  deployment_success_message: |
     Message Card is running on port 8088.
-  args:
+  parameters:
     CARD_TITLE:
       description: "The title to show on the message card"
       required: true
       example: "Hello from Arm"
     CARD_MESSAGE:
       description: "The message to show below the title"
       required: false
-      default: "This page was created from a Topo Template."
+      default: "This page was created from a Topo Project."
       example: "Built once and deployed with Topo"
     ACCENT_COLOR:
       description: "The CSS color used for the card accent"
@@ -163,40 +162,39 @@ x-topo:
       example: "#00a3a3"
 ```
 
-This file is both a Compose file and a Topo Template definition.
+This file is both a Compose file and a Topo Project definition.
 
 The `services` section is standard Compose. The service builds the local `Dockerfile`, publishes the web server on port `8088`, and sets `platform: linux/arm64` so the service targets Arm-based Linux systems.
 
 The `x-topo` section is the Topo metadata block:
 
-- `name` gives the template a human-readable name.
-- `description` explains what the template does.
-- `type` identifies this as an application template.
-- `deploy_success_message` prints a useful hint after deployment.
-- `args` defines the values Topo prompts for when someone clones the template.
+- `name` gives the project a human-readable name.
+- `description` explains what the project does.
+- `deployment_success_message` prints a useful hint after deployment.
+- `parameters` defines the values Topo prompts for when someone clones the project.
 
-The argument names in `x-topo.args` match the keys under `services.message-card.build.args`. When Topo resolves the arguments, it writes the selected values into the build arguments.
+The argument names in `x-topo.parameters` match the keys under `services.message-card.build.args`. When Topo resolves the parameters, it writes the selected values into the build arguments.
 
-The same argument name appears in three places: `x-topo.args` defines what Topo asks for, `build.args` passes the value to Docker, and the Dockerfile `ARG` consumes it.
+The same name appears in three places: `x-topo.parameters` defines what Topo asks for, `build.args` passes the value to Docker, and the Dockerfile `ARG` consumes it.
 
-### Clone the local Topo Template
+### Clone the local Topo Project
 
-Clone your local Topo Template into a new project directory. 
+Clone your local Topo Project into a new project directory. 
 
-You can choose to answer interactive prompts for the arguments:
+You can choose to answer interactive prompts for the project parameters:
 ```bash
 topo clone dir:$HOME/topo-message-card $HOME/message-card-demo
 ```
 
-Alternatively, you can include the arguments in the command:
+Alternatively, you can include the project parameters in the command:
 ```bash
 topo clone dir:$HOME/topo-message-card $HOME/message-card-demo \
   CARD_TITLE="Hello from Arm" \
-  CARD_MESSAGE="Created from a new Topo Template" \
+  CARD_MESSAGE="Created from a new Topo Project" \
   ACCENT_COLOR="#00a3a3"
 ```
 
-After using one of the commands to clone the template, inspect the generated project:
+After using one of the commands to clone the project, inspect the generated project:
 
 ```bash
 cd ~/message-card-demo
@@ -213,7 +211,7 @@ services:
       context: .
       args:
         CARD_TITLE: "Hello from Arm"
-        CARD_MESSAGE: "Created from a new Topo Template"
+        CARD_MESSAGE: "Created from a new Topo Project"
         ACCENT_COLOR: "#00a3a3"
 ```
 
@@ -239,7 +237,7 @@ ssh -L 8088:localhost:8088 user@my-target
 
 Then open `http://localhost:8088/` in your browser.
 
-![Screenshot of the new Topo Template - a web page with the text "Hello from Arm" as the title. This confirms successful deployment and provides a visual reference for the expected result.#center](new_template.png "Hello from Arm web page")
+![Screenshot of the new Topo Project - a web page with the text "Hello from Arm" as the title. This confirms successful deployment and provides a visual reference for the expected result.#center](new_project.png "Hello from Arm web page")
 
 Confirm that the container is running:
 
@@ -251,38 +249,37 @@ The output includes the `message-card` service and port `8088`.
 
 ## (Optional) Add hardware requirements
 
-Add `features` only when your Topo Template needs specific Arm hardware features. For example, a SIMD benchmark that requires SVE can declare that it needs SVE:
+Add `features` only when your Topo Project needs specific Arm hardware features. For example, a SIMD benchmark that requires SVE can declare that it needs SVE:
 
 ```yaml
 x-topo:
   name: "SIMD Visual Benchmark"
   description: |
     Visual demonstration of SIMD performance benefits on Arm processors.
-  type: "application"
   features:
     - "SVE"
 ```
 
-Topo can use these feature requirements when listing templates against a target.
+Topo can use these feature requirements when listing projects against a target.
 
-## Share the Topo Template
+## Share the Topo Project
 
-To share your Topo Template, publish the template directory as a Git repository. Other users can then clone it with Topo:
+To share your Topo Project, publish the project directory as a Git repository. Other users can then clone it with Topo:
 
 ```bash
 topo clone https://github.com/<user-or-org>/topo-message-card.git
 ```
 
-If you want the template to be reused by the wider Topo community, include:
+If you want the project to be reused by the wider Topo community, include:
 
 - `compose.yaml`
 - Any Dockerfiles and source files required by the services
 - A `README.md` with usage instructions
 - A license file
-- Clear `x-topo` metadata and argument descriptions
+- Clear `x-topo` metadata and parameter descriptions
 
 ## What you've accomplished and what's next
 
-You've now created a complete Topo Template from scratch. You created the web page HTML, added a Compose file, described the template with `x-topo` metadata, supplied clone-time arguments, and deployed the generated project to an Arm-based Linux target.
+You've now created a complete Topo Project from scratch. You created the web page HTML, added a Compose file, described the project with `x-topo` metadata, supplied clone-time parameters, and deployed the generated project to an Arm-based Linux target.
 
-Next, you'll learn where to find Agent Skills that can help you create, modify, and review Topo Templates.
+Next, you'll learn where to find Agent Skills that can help you create, modify, and review Topo Projects.