railiance-enablement/SCOPE.md

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

S4 Developer Enablement layer of the Railiance OAS Stack — owns reusable CI/CD templates, developer portal paths, platform templates, SDKs, and buildpacks; uses forge capabilities without owning forge runtime or runner substrate.

---

Core Idea

Railiance is structured as independent repos per OAS Stack layer. This repo is S4: the reusable tools and paved paths that allow the system to evolve. S4 depends on the platform (S3) being operational before tooling can use platform services. S5 applications consume S4 templates and conventions, while railiance-forge provides source hosting, registries, and runner substrate.

---

In Scope

• Reusable CI/CD workflow templates and automation patterns
• Developer portal (self-service deployment interface)
• Platform deployment templates for workloads
• SDKs and libraries for platform consumers
• Buildpacks and image builders
• Handoff contracts to railiance-forge for runner labels, artifact evidence, and registry consumption
• Template references to forge-provided runner labels and credentials documented in /home/worsch/railiance-forge/docs/ci-runner-actions-gitops-ownership.md

---

Out of Scope

• OS-level concerns → railiance-infra (S1)
• Kubernetes runtime → railiance-cluster (S2)
• Platform services → railiance-platform (S3)
• Source forge runtime, container/package registries, runner deployment, runner labels, and runner credentials → railiance-forge
• Application deployments → railiance-apps (S5)
• App-specific workflows, release charts, and source code → app/source repos
• No re-configuration of lower layers from this repo

---

Relevant When

• Setting up CI/CD for the Railiance stack
• Creating or modifying developer tools and deployment templates
• Defining reusable workflow templates that run on forge-provided runners
• Defining promotion conventions and evidence formats consumed by S5
• S3 is operational and tooling layer can now be built

---

Not Relevant When

• S3 (platform services) is not yet operational (pre-condition not met)
• Infrastructure, cluster, or platform work needed (wrong layer)
• The work is Gitea/Forgejo runtime, registry endpoint, package retention, runner deployment, or runner secret access (use railiance-forge)
• The work is a concrete app release or app-specific runbook (use railiance-apps or the source app repo)

---

Current State

• Status: emerging — now owns the forge layer responsibility (decision d151d817, 2026-08-11), which is S4's first concrete owned accountability; still no S4-owned workplans
• Inherited from railiance-forge: runner placement and labels, registry retention, artifact lifecycle, package credentials. The Forgejo workload becomes rapp-forgejo; this layer takes the layer responsibility, because it already declared the handoff contract for exactly those concerns
• Implementation: ArgoCD is deployed in the argocd namespace on CoulombCore as a cluster addon managed from S2 — verified still true 2026-08-12
• But GitOps does not reach the live cluster. ArgoCD is not deployed on railiance01, its Applications target CoulombCore in-cluster, and no railiance01 namespace is ArgoCD-managed. The live workloads deploy by Makefile, outside GitOps. Whether to adopt, retire or relocate ArgoCD is reopened — see railiance-platform/ArchitectureBlueprint.md §5.6
• Stability: n/a for S4-owned content; ArgoCD itself runs, but two of its Applications are Degraded and one is OutOfSync/Missing
• Usage: formal S4 tooling work begins after S3 baseline and should consume runner/registry capabilities from railiance-forge until that migration completes
• Honest gap: this layer's INTENT.md promises considerably more than the repo contains (25 commits, no workplans). Read that as open debt, not description

---

How It Fits

• Upstream dependencies: railiance-platform (S3) must be operational
• Adjacent forge provider: railiance-forge owns source hosting, registries, and runner substrate used by S4 workflows
• Downstream consumers: railiance-apps (S5) uses CI/CD and templates from this layer
• Often used with: railiance-platform (S3), railiance-forge, railiance-apps (S5)

---

Terminology

• Preferred terms: OAS Stack Level S4, developer enablement, paved path, workflow template, promotion convention, boundary rule
• Distinguish "workflow template" from "runner substrate": templates live here; runner deployment, labels, credentials, and health live in railiance-forge.

---

Related / Overlapping

• railiance-platform (S3) — pre-condition; provides services that S4 tooling depends on
• railiance-forge — provides source forge runtime, artifact registries, and runner substrate consumed by S4 workflows; its runner label and GitOps boundary contract is /home/worsch/railiance-forge/docs/ci-runner-actions-gitops-ownership.md
• railiance-apps (S5) — consumer of S4 CI/CD and templates

---

Provided Capabilities

type: infrastructure
title: CI/CD pipeline automation
description: Automated build, test, and deployment pipelines for Railiance workloads — planned for when railiance-platform (S3) is operational.
keywords: [ci, cd, pipeline, automation, template, build, deploy, gitops]

type: documentation
title: Platform deployment templates and SDKs
description: Standardised deployment templates, Helm chart patterns, SDKs, and promotion conventions enabling consistent application deployments across the Railiance stack while consuming forge-owned runners and registries.
keywords: [template, sdk, helm, deployment, developer, buildpack]

---

Getting Oriented

• Start with: CLAUDE.md (session protocol, OAS boundary rules)
• Key files / directories: workplans/ (empty), Makefile
• Pre-conditions: railiance-platform (S3) must be operational