seeded repo

SCOPE.md

@@ -0,0 +1,196 @@
+# SCOPE
+
+This file defines what `railiance-forge` owns, when to use it, and where its
+boundaries stop.
+
+Last reviewed: 2026-06-05
+
+---
+
+## One-liner
+
+Forge and artifact infrastructure for Railiance: current Gitea operation,
+future Forgejo migration, container and package registries, Actions runner
+substrate, artifact lifecycle, and forge operational evidence.
+
+---
+
+## Core Idea
+
+`railiance-forge` separates forge responsibilities from S4 developer
+enablement and S5 application releases.
+
+The practical contract is:
+
+1. lower layers provide servers, Kubernetes runtime, databases, storage, and
+   secret custody;
+2. this repo owns the source forge runtime and artifact publication surface;
+3. `railiance-enablement` owns reusable CI/CD templates and developer paved
+   paths;
+4. `railiance-apps` consumes forge artifacts and deploys user-facing workloads.
+
+No live Gitea files have been migrated here yet. This repo is being founded as
+the future home for that operational surface.
+
+---
+
+## In Scope
+
+- Current Gitea operation and future Forgejo migration/cutover planning.
+- Source forge deployment configuration and runbooks.
+- Container registry and package registry enablement.
+- Registry storage posture, cleanup, retention, and restore readiness.
+- Forge-backed Actions runner substrate:
+  - runner deployment ownership;
+  - runner labels and placement;
+  - runner credential and secret-access boundaries.
+- Artifact publication evidence used by downstream release workflows:
+  - image tags;
+  - package versions;
+  - commit SHA provenance;
+  - promotion and smoke evidence.
+- Forge observability and operator checks:
+  - web endpoint health;
+  - Git SSH health;
+  - registry/package endpoint health;
+  - runner health;
+  - storage growth inspection.
+- Fabric declarations for forge capabilities, interfaces, and dependencies.
+- Repo-local workplan files under `workplans/`.
+
+---
+
+## Out of Scope
+
+- OS provisioning and host hardening: `railiance-infra`.
+- Kubernetes runtime primitives, ingress controllers, and cluster addon
+  installation: `railiance-cluster`.
+- Shared databases, object storage, caches, and runtime secret custody:
+  `railiance-platform`.
+- Generic CI/CD templates, SDKs, buildpacks, and developer portal surfaces:
+  `railiance-enablement`.
+- User-facing application release charts, app runbooks, migrations, and smoke
+  tests: `railiance-apps`.
+- Application source code, package metadata, and image build definitions in
+  source repos.
+- Secret value custody. This repo may reference secret names and approved
+  delivery paths, but it must not commit decrypted secret material.
+
+---
+
+## Relevant When
+
+- Operating or upgrading Gitea as the current Railiance forge.
+- Planning or executing a Forgejo migration or cutover.
+- Enabling or debugging container/package registry behavior.
+- Defining artifact retention, cleanup, provenance, or restore posture.
+- Deploying or operating forge-backed Actions runners.
+- Deciding whether a workflow issue is runner substrate, reusable template, or
+  app-specific release logic.
+- Declaring forge capabilities in Railiance Fabric.
+
+---
+
+## Not Relevant When
+
+- The work is an application release chart or app-specific runbook.
+- The work is a generic workload template or SDK.
+- The work is platform database provisioning or object-storage operation.
+- The work is Kubernetes runtime installation or ingress controller ownership.
+- The work is application source-code behavior.
+- The work requires live secret values outside approved custody paths.
+
+---
+
+## Current State
+
+- Status: founding.
+- Implementation: repository contract and first workplan are being created.
+- Stability: emerging.
+- Usage: intended as the new home for forge responsibilities currently
+  visible in `railiance-apps`.
+
+Known starting point:
+
+- `railiance-apps` currently owns Gitea Helm values, registry overlays, ingress,
+  Gitea Makefile targets, and registry docs.
+- `railiance-enablement` owns the intent for delivery templates and developer
+  paved paths, but not forge runtime operation.
+- `railiance-forge` should absorb forge runtime and artifact infrastructure
+  without moving S5 app release ownership.
+
+---
+
+## How It Fits
+
+- Upstream dependencies:
+  `railiance-infra`, `railiance-cluster`, and `railiance-platform`.
+- Adjacent collaborators:
+  `railiance-enablement` for reusable CI/CD paths and `railiance-apps` for
+  consuming release artifacts in app deployments.
+- Downstream consumers:
+  source repos, app release repos, operators, and Railiance users relying on
+  source hosting and published artifacts.
+
+---
+
+## Terminology
+
+- Preferred terms:
+  forge, source forge, artifact registry, package registry, runner substrate,
+  release evidence.
+- Also known as:
+  Gitea/Forgejo operations, release infrastructure.
+- Potentially confusing terms:
+  "workflow template" belongs in S4 enablement; "runner substrate" belongs
+  here; "app release workflow" belongs near the app or S5 release surface.
+
+---
+
+## Related / Overlapping Repositories
+
+- `railiance-apps` - currently hosts Gitea deployment files and registry docs;
+  should become a consumer after extraction.
+- `railiance-enablement` - owns reusable CI/CD templates, SDKs, buildpacks, and
+  developer portal paths.
+- `railiance-platform` - provides database, storage, backup, and runtime secret
+  services consumed by forge workloads.
+- `railiance-cluster` - provides Kubernetes runtime and cluster-level addons.
+- `railiance-fabric` - should model forge capabilities, interfaces, providers,
+  and consumers.
+
+---
+
+## Getting Oriented
+
+1. Read `AGENTS.md` for session protocol and State Hub conventions.
+2. Read `INTENT.md` for stable purpose.
+3. Read this file for scope and boundaries.
+4. Read active files in `workplans/`.
+5. For migration context, read
+   `/home/worsch/railiance-apps/workplans/RAILIANCE-WP-0006-railiance-forge-extraction.md`.
+
+---
+
+## Provided Capabilities
+
+```capability
+type: infrastructure
+title: Railiance source forge operation
+description: Operate the current Gitea source forge and plan future Forgejo migration/cutover as dedicated Railiance forge infrastructure.
+keywords: [railiance, forge, gitea, forgejo, source-hosting, git]
+```
+
+```capability
+type: infrastructure
+title: Railiance artifact registry operation
+description: Own container and package registry enablement, retention, restore posture, and release artifact evidence for Railiance consumers.
+keywords: [registry, container-image, python-package, artifact, retention, provenance]
+```
+
+```capability
+type: operations
+title: Forge automation runner substrate
+description: Define and operate forge-backed runner infrastructure, runner labels, runner placement, and credential boundaries used by CI/CD workflows.
+keywords: [actions, runner, ci, gitops, automation, credentials]
+```