From 2bc59e98c9aff5e84773152a3d2188c4d8a29b15 Mon Sep 17 00:00:00 2001
From: tegwick <bernd.worsch@gmail.com>
Date: Tue, 17 Mar 2026 23:11:38 +0100
Subject: [PATCH] docs: add SCOPE.md for rapid orientation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 SCOPE.md | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)
 create mode 100644 SCOPE.md

diff --git a/SCOPE.md b/SCOPE.md
new file mode 100644
index 0000000..89c748f
--- /dev/null
+++ b/SCOPE.md
@@ -0,0 +1,90 @@
+# SCOPE
+
+> This file helps you quickly understand what this repository is about,
+> when it is relevant, and when it is not.
+> It is intentionally lightweight and may be incomplete.
+
+---
+
+## One-liner
+
+S5 Workloads & Experience layer of the Railiance OAS Stack — owns application Helm releases and Kubernetes manifests for user-facing services (Gitea, coulomb services, web frontends).
+
+---
+
+## Core Idea
+
+Railiance is structured as five independent repos, one per OAS (Open Application Stack) layer. This repo is S5 — the top layer. It owns application-level deployments: Helm values and manifests for Gitea, coulomb services, APIs, and web portals. It depends on S1–S4 being operational before it can do anything.
+
+---
+
+## In Scope
+
+- Application Helm releases: Gitea, coulomb services, web portals, APIs
+- Kubernetes manifests for user-facing workloads
+- Application-level configuration and deployment orchestration
+
+---
+
+## Out of Scope (per ADR-003)
+
+- OS-level concerns → railiance-infra (S1)
+- Kubernetes runtime → railiance-cluster (S2)
+- Platform services (PostgreSQL, caches, storage) → railiance-platform (S3)
+- Developer tooling (CI/CD, portals) → railiance-enablement (S4)
+- No re-configuration of lower layers from this repo
+
+---
+
+## Relevant When
+
+- Deploying or updating user-facing applications in the Railiance stack
+- S1–S4 are all operational and it's time to deploy workloads
+
+---
+
+## Not Relevant When
+
+- S1–S4 are not yet operational (pre-conditions not met)
+- Infrastructure, cluster, or platform work needed (wrong layer)
+- No user-facing applications to deploy
+
+---
+
+## Current State
+
+- Status: experimental (placeholder; no active work)
+- Implementation: empty (workplans/ has only .gitkeep; no Helm charts yet)
+- Stability: n/a
+- Usage: will be used after railiance-platform (S3) is operational
+
+---
+
+## How It Fits
+
+- Upstream dependencies: railiance-infra (S1) → railiance-cluster (S2) → railiance-platform (S3) → railiance-enablement (S4) → this repo (S5)
+- Downstream consumers: end users accessing Gitea, coulomb services, web portals
+- Often used with: railiance-platform (database/cache backends), net-kingdom (identity for apps)
+
+---
+
+## Terminology
+
+- Preferred terms: OAS Stack Level S5, workloads, experience endpoints, boundary rule
+- Potentially confusing terms: "S5" is a stack level designation, not a version
+
+---
+
+## Related / Overlapping Repositories
+
+- `railiance-platform` (S3) — provides database, cache, identity services consumed by S5 apps
+- `railiance-enablement` (S4) — provides CI/CD and templates that S5 uses
+- `railiance-cluster` (S2) — Kubernetes runtime where S5 workloads run
+
+---
+
+## Getting Oriented
+
+- Start with: `CLAUDE.md` (session protocol, boundary rules)
+- Key files / directories: `workplans/` (currently empty), `Makefile`
+- Pre-conditions: all four lower layers (S1–S4) must be converged and verified