From 7c4f866606109ab278081f5e5e5e0d7df236f8fa Mon Sep 17 00:00:00 2001
From: Pedro Faria da Costa <pedrof.dacosta@icloud.com>
Date: Mon, 6 Jul 2026 00:06:29 +0100
Subject: [PATCH] update readme

---
 .forgejo/workflows/infra.yml |  3 ++-
 Makefile                     | 13 ++++++++++++-
 README.md                    | 18 ++++++++++++++++++
 3 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/.forgejo/workflows/infra.yml b/.forgejo/workflows/infra.yml
index ee53a44..8f72735 100644
--- a/.forgejo/workflows/infra.yml
+++ b/.forgejo/workflows/infra.yml
@@ -3,6 +3,7 @@ name: Infrastructure
 on:
   push:
     branches: [main]
+    tags: ['v*']
     paths: ['infra/**']
   pull_request:
     branches: [main]
@@ -46,7 +47,7 @@ jobs:
   apply:
     runs-on: docker
     needs: plan
-    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    if: (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')) && github.event_name == 'push'
     steps:
       - uses: actions/checkout@v4
 
diff --git a/Makefile b/Makefile
index 3b13639..b3f385d 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: build run clean help infra-up infra-down infra-logs run-engine run-web infra-init infra-plan infra-apply
+.PHONY: build run clean help infra-up infra-down infra-logs run-engine run-web infra-init infra-plan infra-apply release
 
 # Command Variables
 DOCKER_COMPOSE=docker compose
@@ -44,6 +44,17 @@ clean: infra-down
 	$(MAKE) -C tongo-core clean
 	$(DOCKER_COMPOSE) down -v
 
+## release: Create and push a new production release tag (usage: make release TAG=v1.0.0)
+release:
+	@if [ -z "$(TAG)" ]; then \
+		echo "Error: TAG variable is required. Example: make release TAG=v1.0.0"; \
+		exit 1; \
+	fi
+	@echo "Creating production release tag $(TAG)..."
+	git tag -a $(TAG) -m "Production release $(TAG)"
+	@echo "Pushing tag $(TAG) to origin..."
+	git push origin $(TAG)
+
 ## help: Show this help
 help:
 	@grep -E '^## ' Makefile | sed 's/## //' | column -t -s ':'
diff --git a/README.md b/README.md
index 4bbb0a2..2e638d3 100644
--- a/README.md
+++ b/README.md
@@ -51,5 +51,23 @@ Visit the console at `http://localhost:3000`.
 
 ---
 
+## 🚀 Release Process & CI/CD
+
+This monorepo uses **Forgejo Actions** and **OpenTofu Workspaces** to manage deployments across isolated environments:
+
+*   **Staging (`staging.holo-grid.bar`)**: Target for active development. Any direct push or merge to the `main` branch automatically provisions staging infrastructure and deploys the staging code stack.
+*   **Production (`holo-grid.bar`)**: Target for stable releases. Pushing a Git version tag (e.g. `v1.0.0`) automatically provisions production infrastructure and deploys the release code stack.
+
+### Triggering a Production Release
+
+You can create and push a new release tag directly using the Makefile:
+
+```bash
+# Create and push release tag v1.0.0
+make release TAG=v1.0.0
+```
+
+---
+
 ## 📜 Ferengi Code of Conduct
 > "The riskier the road, the greater the profit." — Rule of Acquisition #62