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, with reusable Forgejo workflow templates and the railiance01 ArgoCD declared state (RAIL-EN-WP-0002 active).
• S4 owns the consumer-facing contract for runner labels, registries, credentials, and artifact evidence. railiance-forge continues to operate those capabilities; they are not duplicated here.
• Implementation: Argo CD Core v3.5.3 (headless) is installed on railiance01 in namespace argocd since 2026-09-21. ArchitectureBlueprint §5.6 (railiance-platform) is settled as adopt properly. Its declared state is deploy/argocd/railiance01/ (RAIL-EN-WP-0002). It has 0 Applications and 0 AppProjects, so no workload is under GitOps yet; the live workloads still deploy by Makefile. Adoption (phase B) and retiring CoulombCore's ArgoCD (phase C) each need a founder go-ahead
• Stability: the pinned install matches live (read-only server-side diff, 2026-09-21); resource requests/limits are declared but not yet applied, so the pods are BestEffort until RAIL-EN-WP-0002-T02
• 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. 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: workflows/, docs/, workplans/, Makefile
• Pre-conditions: railiance-platform (S3) must be operational