diff --git a/docs/spec/README.md b/docs/spec/README.md
index 9024044a..fe998f6c 100644
--- a/docs/spec/README.md
+++ b/docs/spec/README.md
@@ -24,11 +24,16 @@ source manager would make Flux and Helm Operator resilient to outbound connectiv
 simplify the state machine(s) that these controllers operate.
 
 Managing the source operations in a dedicated controller could enable Flux to compose the desire state of a cluster
-from multiple source.
-Furthermore, the manifests transformation process could be performed by 3rd party tools
+from multiple source. Furthermore, the manifests transformation process could be performed by 3rd party tools
 (e.g. kustomize, jk, tanka, cue run by Tekton pipelines or Kubernetes Jobs)
 that subscribe to source changes events.
 
+The source controller could enable pinning the cluster desired state to a specific Git commit or Git tag.
+
+For teams that are using semantic versioning, the source controller could monitor the Git repository tags 
+and set the cluster desired state to the latest release or to a tag that matches a semver pattern.
+In a similar fashion, a semver pattern could trigger Helm chart upgrades without manual intervention from users.
+
 ## Goals
 
 The main goal is to define a set of Kubernetes objects that cluster admins and various automated operators
diff --git a/docs/spec/v1alpha1/gitrepositories.md b/docs/spec/v1alpha1/gitrepositories.md
index 080c764b..18df0b02 100644
--- a/docs/spec/v1alpha1/gitrepositories.md
+++ b/docs/spec/v1alpha1/gitrepositories.md
@@ -18,7 +18,7 @@ type GitRepositorySpec struct {
 	// +optional
 	SecretRef *v1.LocalObjectReference `json:"secretRef,omitempty"`
 	
-	// The git reference to checkout and monitor for changes.
+	// The git reference to checkout and monitor for changes, defaults to master branch.
 	// +optional
 	Reference *GitRepositoryRef `json:"ref,omitempty"`
 
@@ -28,7 +28,7 @@ type GitRepositorySpec struct {
 
 // GitRepositoryRef defines the git ref used for pull and checkout operations
 type GitRepositoryRef struct {
-	// The git branch to checkout, defaults to ('master').
+	// The git branch to checkout, defaults to master.
 	// +optional
 	Branch string `json:"branch"`