Add component workflow docs

docs/concepts/developer-abstractions.md

@@ -95,28 +95,39 @@ enables platform teams to control infrastructure policies while developers focus
 limits, scaling parameters, and operational policies come from the ServiceClass or WebApplicationClass, while the 
 workload simply declares what the application needs to function.
 
-## WorkflowRun
-
-A **WorkflowRun** represents a runtime execution instance of a Workflow. While Workflows define the template and schema
-for what can be executed, WorkflowRuns represent actual executions with specific parameter values and context.
-
-WorkflowRuns bridge the gap between developer intent and CI/CD execution. Developers create WorkflowRun resources to
-trigger workflows, providing only the schema values defined in the Workflow template. The platform handles all the
-complexity of rendering the final workflow specification, synchronizing secrets, and managing execution in the build
-plane.
-
-Each WorkflowRun captures two essential pieces of information:
-
-**Workflow Configuration** references the Workflow template to use and provides the developer-configured schema values.
-These values conform to the schema defined in the referenced Workflow, with automatic validation ensuring type
-correctness and constraint satisfaction. For example, a Docker build workflow might receive repository URL, branch
-name, and Dockerfile path, while a buildpack workflow might receive additional configuration for build resources,
-caching, and testing modes.
-
-This abstraction provides a simplified interface where developers interact with curated schemas rather than complex
-CI/CD pipeline definitions, while creating permanent audit trails essential for compliance and debugging. The separation
-of concerns allows platform engineers to control workflow implementation and security policies through Workflow templates
-while developers manage application-specific parameters through WorkflowRun schema values. For component-bound workflows,
-automatic linkage between builds and components enables coordinated build and deployment lifecycles. WorkflowRuns can be
-created manually for ad-hoc builds or automatically by platform controllers in response to code changes, supporting both
-interactive development and fully automated CI/CD pipelines while maintaining consistent execution patterns and governance.
+## ComponentWorkflowRun
+
+A **ComponentWorkflowRun** represents a runtime execution instance of a ComponentWorkflow - a specialized workflow type
+designed specifically for building components. While ComponentWorkflows define the build template and schema,
+ComponentWorkflowRuns represent actual build executions with specific parameter values and ownership tracking.
+
+ComponentWorkflowRuns bridge the gap between developer intent and CI/CD execution for component builds. Developers
+create ComponentWorkflowRun resources to trigger builds, providing component ownership information, repository details,
+and build parameters. The platform handles all the complexity of rendering the final workflow specification,
+synchronizing secrets, and managing execution in the build plane.
+
+Each ComponentWorkflowRun captures three essential pieces of information:
+
+**Ownership Tracking** links the build execution to a specific component and project. This enables traceability,
+allowing the platform to track which builds belong to which components and maintain build history per component. The
+ownership information includes both project name and component name, ensuring proper audit trails and enabling
+component-specific build operations.
+
+**System Parameters** provide the structured repository information required for build-specific platform features. These
+parameters follow a fixed structure with `repository.url`, `repository.revision.branch`, `repository.revision.commit`,
+and `repository.appPath` fields. This predictable structure enables the platform to support auto-builds triggered by
+webhooks, manual build actions in the UI, build traceability linking images to source commits, and monorepo support by
+identifying specific application paths within repositories.
+
+**Developer Parameters** provide values for the flexible configuration schema defined by the platform engineer in the
+ComponentWorkflow. These might include build version numbers, test modes, resource allocations, timeout settings,
+caching configurations, and retry limits. The schema validation ensures type correctness and constraint satisfaction
+automatically.
+
+This abstraction provides a specialized interface for component builds, where developers interact with curated schemas
+rather than complex CI/CD pipeline definitions. The separation of concerns allows platform engineers to control build
+implementation and security policies through ComponentWorkflow templates while developers manage repository information
+and build parameters through ComponentWorkflowRun instances. ComponentWorkflowRuns can be created manually for ad-hoc
+builds or automatically by platform controllers in response to code changes, supporting both interactive development and
+fully automated CI/CD pipelines while maintaining consistent execution patterns and governance specifically tailored for
+component build operations.

docs/concepts/platform-abstractions.md

@@ -165,42 +165,55 @@ application patterns. Platform engineers create ComponentTypes that encode organ
 applications securely and efficiently, while developers benefit from simplified configuration and automatic compliance
 with platform standards.
 
-## Workflows
-
-A **Workflow** is a platform engineer-defined template for executing build, test, and automation tasks in OpenChoreo.
-Workflows provide a schema-driven interface that separates developer-facing parameters from platform-controlled
-configurations, enabling developers to trigger complex CI/CD processes through simple, validated inputs.
-
-Workflows in OpenChoreo integrate with Argo Workflows to provide Kubernetes-native execution for continuous
-integration tasks. Unlike traditional CI/CD systems where developers must understand pipeline implementation details,
-OpenChoreo Workflows present a curated schema of configurable options while platform engineers control the underlying
-execution logic, security policies, and infrastructure configurations.
-
-Each Workflow defines a **schema** that specifies what developers can configure when creating a run instance.
-This schema uses the same inline type definition syntax as ComponentTypes, making validation rules explicit and
-self-documenting. The schema typically includes repository configuration, build parameters, resource limits, and
-testing options, with type validation, default values, and constraints enforced automatically.
-
-The Workflow's **resource template** contains the actual Argo Workflow specification with CEL expressions for dynamic
-value injection. These expressions access three categories of variables:
-
-**Context variables** (`${ctx.*}`) provide runtime information like the workflow run name, component name, project name, and
-organization name. These enable unique resource naming and proper isolation across
-executions.
-
-**Schema variables** (`${schema.*}`) inject developer-provided values from the WorkflowRun instance. These include
-repository URLs, build configurations, and other parameters defined in the workflow schema.
-
-**Platform-controlled parameters** are hardcoded directly in the workflow and remain invisible to developers. These may
-include container image references, registry URLs, security scanning configurations, and organizational policies. By
-hardcoding these values, platform engineers ensure compliance with security standards and infrastructure policies
-regardless of developer input.
-
-Workflows can be referenced by Components through the `workflow` field, enabling automated builds triggered by code
-changes or manual developer actions. ComponentTypes can restrict which Workflows are allowed through the
-`allowedWorkflows` field, ensuring that different component types use appropriate build strategies and security
-policies.
-
-The Workflow abstraction thus provides a controlled interface to powerful CI/CD capabilities, enabling platform teams
-to offer self-service build automation while maintaining governance over build processes, security scanning, artifact
-storage, and compliance requirements.
+## ComponentWorkflow
+
+A **ComponentWorkflow** is a platform engineer-defined template specifically designed for building components in
+OpenChoreo. Unlike generic automation workflows, ComponentWorkflows enforce a structured schema for repository
+information while providing flexibility for additional build configuration, enabling powerful build-specific platform
+features like auto-builds, webhooks, and build traceability.
+
+ComponentWorkflows address the unique requirements of component builds that generic workflows cannot solve. Component
+builds need to power manual build actions in the UI, integrate with Git webhooks for auto-builds, maintain build
+traceability linking container images to source commits, and support monorepo structures by identifying specific
+application paths. These features require the platform to reliably locate critical repository fields, which is only
+possible with a predictable schema structure.
+
+Each ComponentWorkflow defines three key sections:
+
+**System Parameters Schema** enforces a required structured schema for repository information. This schema must follow
+a specific structure with `repository.url`, `repository.revision.branch`, `repository.revision.commit`, and
+`repository.appPath` fields, all of type string. Platform engineers can customize defaults, enums, and descriptions
+within each field, but must maintain the field names, nesting structure, and types. This predictable structure enables
+build-specific platform features to work reliably across all component workflows while still giving platform engineers
+control over validation rules and default values.
+
+**Developer Parameters Schema** provides complete freedom for platform engineers to define additional build
+configuration. This flexible schema can include any structure the platform engineer designs - build version numbers,
+test modes, resource allocations, timeout settings, caching configurations, retry limits, and more. The schema supports
+all types including integers, booleans, strings, arrays, and nested objects, with full validation through defaults,
+minimums, maximums, and enums. This separation between required system parameters and flexible developer parameters
+balances platform reliability with configuration freedom.
+
+**Run Template** contains the actual Kubernetes resource specification (typically an Argo Workflow) with template
+variables for dynamic value injection. These expressions access context variables like `${ctx.componentWorkflowRunName}`,
+`${ctx.componentName}`, `${ctx.projectName}`, and `${ctx.orgName}` for runtime information, system parameter values
+through `${systemParameters.*}` for repository details, and developer parameter values through `${parameters.*}` for
+custom configuration. Platform engineers can also hardcode platform-controlled parameters directly in the template,
+such as builder images, registry URLs, security scanning settings, and organizational policies.
+
+ComponentTypes govern which ComponentWorkflows developers can use through the `allowedWorkflows` field. This enables
+platform engineers to enforce build standards per component type, ensuring that web applications use approved frontend
+build tools, backend services use appropriate security scanners, and different component types follow their specific
+build requirements.
+
+Components reference ComponentWorkflows in their `workflow` field, providing the system parameters for repository
+information and developer parameters for build configuration. The platform handles template rendering, secret
+synchronization, and execution management in the build plane, with ComponentWorkflowRun resources tracking individual
+build executions.
+
+The ComponentWorkflow abstraction thus provides a specialized interface for component builds that balances platform
+needs with developer flexibility. Platform engineers control build implementation, security policies, and
+infrastructure configurations while ensuring build-specific features work reliably. Developers get a simplified
+interface for configuring builds without managing complex CI/CD pipeline definitions. The separation from generic
+workflows makes clear that component builds have unique requirements deserving dedicated abstractions, while
+maintaining the schema-driven approach that characterizes OpenChoreo's architecture.