Changes from David (#14)

Co-authored-by: Nick Chase <nchase@earthlink.net>

Author: nickchase

README.md

@@ -1,4 +1,53 @@
-This project uses [MkDocs](https://www.mkdocs.org/)
+# CG DevX Documentation
+
+Welcome to the documentation for **CG DevX**, a delivery framework that applies the best practices of Platform Engineering to improve the way teams build, deploy, and operate cloud-native applications.
+
+## Purpose
+
+CG DevX helps organizations unlock the potential of cloud-native software development and deployment by introducing structure and delivery discipline to the software lifecycle. Built on Kubernetes, containers, and GitOps principles, it enables robust, resilient, and repeatable workflows that scale across teams and environments.
+
+Unlike generic platform toolkits, CG DevX applies opinionated Platform Engineering patterns to:
+
+- Reduce delivery variation
+- Accelerate developer onboarding
+- Enforce organizational standards by design
+
+## Key Concepts
+
+- **Platform Engineering**: A structured approach to delivering internal platforms and workflows that codify best practices.
+- **Golden Paths**: Curated workflows that provide production-ready defaults for building and deploying applications.
+- **Scaffold-as-Code**: Automated project bootstrapping with built-in CI/CD pipelines, test harnesses, and observability defaults.
+- **GitOps-Driven Deployment**: Declarative infrastructure and application delivery with version control, policy enforcement, and rollback support.
+
+## Audience
+
+This documentation is intended for:
+
+- Platform Engineering and DevOps teams
+- SREs building internal delivery workflows
+- Application developers onboarding to CG DevX
+- Cloud architects designing scalable, compliant delivery systems
+
+## Structure
+
+- [`/platform_engineering/`](./platform_engineering): Overview of the delivery discipline and structured approach behind CG DevX
+- [`/cgdevx/`](./cgdevx): Technical details of CG DevX components and how they are applied in practice
+- [`/`](./): Project overview and introduction to the documentation
+
+## Goals
+
+By adopting CG DevX, organizations can:
+
+- Deliver software more reliably and securely
+- Shift from ad hoc DevOps workflows to governed delivery pipelines
+- Enable application teams to move faster, with confidence in production readiness
+
+
+CG DevX brings engineering rigor to cloud-native software delivery — turning internal tools and infrastructure into products that scale with your teams.
+
+## Contributing
+
+This project uses [MkDocs](https://www.mkdocs.org/).
 
 To install MkDocs and required plugins run 
 
@@ -16,24 +65,24 @@ pip install mkdocs mkdocs-mermaid2-plugin mkdocs-drawio-file
 └── mkdocs.yml
 
 ```
-mkdocs.yml contains project configuration file. 
-Documentation source files are located in a folder named `docs`. 
-Documentation entry point is `index.md` file.
+The configuration file is `mkdocs.yml`, and 
+documentation source files are located in the `docs` folder. 
+The documentation entry point is `index.md`.
 
-To run in a local dev-server mode, run the mkdocs serve command:
+To run in a local dev-server mode, run the `mkdocs serve` command:
 
 ```shell
 mkdocs serve
 ```
 
-Documentation website should be available at http://127.0.0.1:8000/
+The documentation website will be available at http://127.0.0.1:8000/.
 
-To build a static website run build documentation command: 
+To build a static website run the build documentation command: 
 
 ```shell
 mkdocs build
 ```
-This output will be generated to the directory named `site`.
+This output will be generated to the `site` directory.
 
 To host using [GitHub Pages](https://pages.github.com/) and deploy to a branch `gh-pages`, run the following command: 
 

docs/index.md

@@ -1,15 +1,68 @@
-# What is CG DevX?
+# Welcome to CG DevX
 
-Welcome to CG DevX, an all-in-one platform designed to simplify and enhance the development, deployment, and management
-of cloud-native applications. Whether you are an experienced platform engineer or just a beginner starting your DevOps
-and cloud-native journey, CG DevX provides the tools and capabilities to empower your team and streamline your
-workflows.
+`cg-devx` is a Platform Engineering toolkit designed to improve software delivery outcomes by introducing consistency, automation, and engineering discipline into the application lifecycle.
 
-## Getting Started
+## Why It Matters
 
-Ready to dive into CG DevX? Our comprehensive documentation and guides are your go-to resource. Get started with
-installation, explore configuration options, discover best practices, and unlock advanced features. Join the CG DevX
-community to connect with other users, share knowledge, and collaborate on cloud-native development.
+DevOps helped close the gap between developers and operations, but it often led to fragmented tooling and inconsistent workflows. As organizations scale, this approach struggles to ensure security, compliance, and repeatability.
 
-CG DevX empowers developers and teams to embrace cloud-native practices, supercharge their software delivery, and
-enhance operational efficiency.
+Platform Engineering builds on the principles of DevOps but formalizes them into structured, reusable systems. With `cg-devx`, teams adopt shared standards for delivery, reduce variation across environments, and scale developer productivity without sacrificing governance.
+
+## What is `cg-devx`?
+
+`cg-devx` enables internal platform teams to provide developers with a curated, reliable application delivery experience. It combines:
+
+- **Golden Paths**: Pre-defined, production-ready workflows for new services
+- **GitOps Automation**: Declarative infrastructure and application delivery
+- **Scaffold-as-Code**: Service bootstrapping with integrated pipelines, observability, and policies
+
+## Key Benefits
+
+- Standardizes onboarding for application teams
+- Encodes delivery best practices into platform services
+- Enables secure, repeatable delivery at scale
+
+---
+
+`cg-devx` supports organizations transitioning from DevOps culture to formalized platform engineering practice, making delivery more predictable, governed, and scalable.
+
+# The `cgdevx` Toolkit
+
+`cgdevx` provides the foundational tooling for platform teams to build and maintain Internal Developer Platforms (IDPs) that scale delivery discipline across organizations.
+
+## Why Use `cgdevx`?
+
+Software delivery often starts with informal scripts and manual pipelines. As systems grow, these approaches become hard to scale, audit, or govern.
+
+`cgdevx` introduces structure and versioning into delivery workflows, turning best practices into reusable, sharable assets.
+
+## Toolkit Capabilities
+
+### Scaffold-as-Code
+
+Standardized scaffolding ensures new services begin with compliant and production-ready defaults:
+
+- CI/CD pipelines
+- Linting and testing frameworks
+- Observability configuration
+- Security policies and deployment gates
+
+### Golden Paths
+
+Golden Paths encode curated delivery workflows that are:
+
+- Reproducible across environments
+- Aligned with security and compliance policies
+- Version-controlled for traceability
+
+### GitOps Automation
+
+`cgdevx` integrates with GitOps controllers to:
+
+- Enforce infrastructure immutability
+- Enable declarative, rollback-friendly deployments
+- Support policy-as-code enforcement across environments
+
+## Supporting Delivery Contracts
+
+The toolkit enables platform teams to define and enforce delivery contracts — shared agreements encoded as code, ensuring application teams can move quickly without bypassing compliance and security.

docs/platform_engineering.md

@@ -1,46 +1,29 @@
-# Platform Engineering
+# Platform Engineering at CloudGeometry
 
-[//]: # (TODO: recap of PE and IDP key aspects)
+## From DevOps to Platform Engineering
 
-[//]: # (https://humanitec.com/platform-engineering)
+DevOps emerged to bridge the gap between developers and operations. While effective in fostering collaboration, it often resulted in team-specific tooling, tribal knowledge, and a lack of delivery standardization.
 
-[//]: # (https://humanitec.com/blog/what-is-an-internal-developer-platform)
+As delivery complexity increases, this model becomes brittle. Platform Engineering addresses these limitations by introducing shared infrastructure, governance, and delivery contracts that ensure consistency and compliance across teams.
 
+## Platform Engineering as Engineering Discipline
 
-Platform engineering is a new discipline that emerged in response to the growing complexity of modern cloud-native
-architectures. It describes the practice of building and maintaining an integrated product, called an "Internal
-Developer Platform," which acts as a flexible and supported abstraction layer between developers and the underlying
-technologies of their applications.
+At its core, Platform Engineering is about applying engineering rigor to internal tools and services:
 
-The goal of platform engineering is to improve developer productivity through improving the developer experience (
-DevEx).
+- **Version-controlled delivery workflows**
+- **Reusable infrastructure modules**
+- **Defined interface contracts between teams**
+- **Observability and policy enforcement as defaults**
 
-Internal developer platforms improve the velocity and happiness of teams by enabling developer self-service and reducing
-cognitive load on developers.
+Rather than relying on informal practices, platform teams build services that encode delivery best practices as productized capabilities.
 
-Core benefits of Platform Engineering and Internal Developer Platforms:
+## Why Internal Developer Platforms (IDPs) Matter
 
-- **Faster innovation**: Faster time to launch, frequent updates, focus on business problems
-- **Higher quality**: Fewer environment issues, more deterministic test results, faster rollback
-- **Increased reliability**: Observable services, graceful degradation, improved business continuity, optimisation for a
-  fluctuating load
-- **Improved security**: Reduced security engineering overhead, Improved security
-  operations and governance
-- **Improved ways of working**: Define policy via experimentation and simpler processes, apply enabling constraints,
-  zero downtime updates
-- **Reduced costs**: Economies of scale, easier cost management
-- **Better productivity**: Lower cognitive load, easier to identify talent needs
+IDPs created via Platform Engineering empower developers while enforcing guardrails. They simplify workflows, reduce cognitive overhead, and ensure that delivery pipelines meet organizational standards — by design, not convention.
 
-Platform Engineering and the Internal Developer Platform is:
+## Outcomes You Can Expect
 
-- **Not a commodity**: It cannot be bought off the shelf, as it must satisfy the specific needs of your organisation.
-  It’s
-  built by weaving together open-source and bespoke commodity tools to create a technology accelerator.
-- **Not a project**: It isn’t a one-off development with a fixed end date. It will keep changing, as the needs of your
-  teams will change based on their customers’ demands.
-- **Not a universal infrastructure platform**: It cannot run all cloud services for all possible consumers. It needs to
-  focus on a subset of cloud services to support specific workloads.
+- Increased release velocity with fewer regressions
+- Built-in compliance through delivery standardization
+- Lower onboarding costs for new services and teams
 
-It’s important to remember that an Internal Developer Platform isn’t a silver bullet. It’s a long-term commitment to
-providing Services at scale.
-It’s not appropriate for all workloads, teams, or organizations.