docs(devops): group Gitea runner docs under gitea-runner/ subfolder

Moves 5 related docs into docs/devops/gitea-runner/ to keep this multi-doc workstream from colliding with future roadmaps and delegation prompts in docs/devops/. Renames: HOSTINGER_GITEA_RUNNER_ROADMAP.md -> ROADMAP.md HOSTINGER_GITEA_ACT_RUNNER_SETUP.md -> ACT_RUNNER_SETUP.md GITEA_PACKAGES_PUBLISH_WORKFLOW.md -> PUBLISH_WORKFLOW.md HOSTINGER_GITHUB_RUNNER_SETUP.md -> _PLAN_B_GITHUB_RUNNER.md CODEX_DELEGATION_PROMPT.md -> (same name, moved) All internal cross-links updated via sed sweep. Verified no stale references remain. Adds README.md in the new folder as the index + pattern doc for future multi-doc workstreams (one-liner handoff, file map, architecture summary). Updated one-liner handoff path: Read docs/devops/gitea-runner/CODEX_DELEGATION_PROMPT.md ...
2026-05-24 18:33:45 -07:00 · 2026-05-24 18:33:45 -07:00 · 7381d0f5c0
commit 7381d0f5c0
parent 82cdebeb87
6 changed files with 63 additions and 26 deletions
--- a/docs/devops/HOSTINGER_GITEA_ACT_RUNNER_SETUP.md
+++ b/docs/devops/HOSTINGER_GITEA_ACT_RUNNER_SETUP.md
@ -1,15 +1,15 @@
 # Hostinger VM — Gitea Actions `act_runner` Setup

-> 📋 **Track progress in the master roadmap:** [`HOSTINGER_GITEA_RUNNER_ROADMAP.md`](./HOSTINGER_GITEA_RUNNER_ROADMAP.md). The roadmap has the checklist; this doc has the implementation detail. Codex updates checkboxes + commit hashes in the roadmap as each phase completes.
+> 📋 **Track progress in the master roadmap:** [`ROADMAP.md`](./ROADMAP.md). The roadmap has the checklist; this doc has the implementation detail. Codex updates checkboxes + commit hashes in the roadmap as each phase completes.

 > **Delegation prompt for the Codex agent running on the Hostinger VM.**
 > Canonical CI runner setup for the ByteLyst ecosystem. Read top-to-bottom before executing. Stop and ask the human if any pre-flight check fails or any deliverable is unclear.

 > Companion docs:
 >
-> - [`HOSTINGER_GITEA_RUNNER_ROADMAP.md`](./HOSTINGER_GITEA_RUNNER_ROADMAP.md) — **execution tracker (this doc's checklist)**.
-> - [`GITEA_PACKAGES_PUBLISH_WORKFLOW.md`](./GITEA_PACKAGES_PUBLISH_WORKFLOW.md) — the publish workflow this runner executes.
-> - [`HOSTINGER_GITHUB_RUNNER_SETUP.md`](./HOSTINGER_GITHUB_RUNNER_SETUP.md) — Plan B (GitHub Actions runner). Kept for reference.
+> - [`ROADMAP.md`](./ROADMAP.md) — **execution tracker (this doc's checklist)**.
+> - [`PUBLISH_WORKFLOW.md`](./PUBLISH_WORKFLOW.md) — the publish workflow this runner executes.
+> - [`_PLAN_B_GITHUB_RUNNER.md`](./_PLAN_B_GITHUB_RUNNER.md) — Plan B (GitHub Actions runner). Kept for reference.

 ---

@ -628,7 +628,7 @@ sudo rm /usr/local/bin/act_runner

 Once this runner passes all E2E criteria:

-1. Implement [`GITEA_PACKAGES_PUBLISH_WORKFLOW.md`](./GITEA_PACKAGES_PUBLISH_WORKFLOW.md) — the actual `publish-packages.yml` workflow for `@bytelyst/*` packages, modeled after the E2E template.
+1. Implement [`PUBLISH_WORKFLOW.md`](./PUBLISH_WORKFLOW.md) — the actual `publish-packages.yml` workflow for `@bytelyst/*` packages, modeled after the E2E template.
 2. Propagate that workflow to all 20+ repos (script-driven).
 3. Add a SKILL doc at `AI.dev/SKILLS/gitea-package-publishing.md`.

--- a/docs/devops/gitea-runner/CODEX_DELEGATION_PROMPT.md
+++ b/docs/devops/gitea-runner/CODEX_DELEGATION_PROMPT.md
@ -13,13 +13,13 @@ you're running on. Read and follow the master roadmap exactly.
 REPO: learning_ai_common_plat
  Find it: `find ~ -maxdepth 4 -type d -name "learning_ai_common_plat" 2>/dev/null | head -3`

-ROADMAP: docs/devops/HOSTINGER_GITEA_RUNNER_ROADMAP.md
+ROADMAP: docs/devops/gitea-runner/ROADMAP.md

 INSTRUCTIONS:

 1. Read the roadmap top-to-bottom BEFORE starting any work. It points to
-   two companion docs (HOSTINGER_GITEA_ACT_RUNNER_SETUP.md and
-   GITEA_PACKAGES_PUBLISH_WORKFLOW.md) for implementation detail —
+   two companion docs (ACT_RUNNER_SETUP.md and
+   PUBLISH_WORKFLOW.md) for implementation detail —
   read those too.

 2. Execute phases P0 → P5 in order. Do NOT skip phases.
@ -94,13 +94,13 @@ START WITH P0. Read the roadmap. Then go.
 ## One-liner handoff (paste this single line to Codex)

 ```
-Read docs/devops/CODEX_DELEGATION_PROMPT.md in learning_ai_common_plat, then execute the prompt within. Begin with P0.
+Read docs/devops/gitea-runner/CODEX_DELEGATION_PROMPT.md in learning_ai_common_plat, then execute the prompt within. Begin with P0.
 ```

 Or, if Codex doesn't have the repo yet:

 ```
-Clone https://github.com/saravanakumardb1/learning_ai_common_plat (or whichever remote you can reach), open docs/devops/CODEX_DELEGATION_PROMPT.md, and execute the prompt within. Begin with P0.
+Clone https://github.com/saravanakumardb1/learning_ai_common_plat (or whichever remote you can reach), open docs/devops/gitea-runner/CODEX_DELEGATION_PROMPT.md, and execute the prompt within. Begin with P0.
 ```

 ---
@ -125,7 +125,7 @@ It should stop and surface the question itself. If it doesn't, you can:

 1. Check the latest roadmap state on `origin/main`:
   ```bash
-   git fetch origin && git show origin/main:docs/devops/HOSTINGER_GITEA_RUNNER_ROADMAP.md | grep -E "^\- \[" | head -30
+   git fetch origin && git show origin/main:docs/devops/gitea-runner/ROADMAP.md | grep -E "^\- \[" | head -30
   ```
 2. Find the lowest unchecked `[ ]`.
 3. Tell Codex: "Resume from P<x>.<y>. The roadmap state is current as of commit `<sha>`."
--- a/docs/devops/GITEA_PACKAGES_PUBLISH_WORKFLOW.md
+++ b/docs/devops/GITEA_PACKAGES_PUBLISH_WORKFLOW.md
@ -1,14 +1,14 @@
 # `@bytelyst/*` Package Publish Workflow (Gitea Actions)

-> 📋 **Track progress in the master roadmap:** [`HOSTINGER_GITEA_RUNNER_ROADMAP.md`](./HOSTINGER_GITEA_RUNNER_ROADMAP.md) — Phase 4 references this doc. Codex updates the roadmap checkboxes as each step here completes.
+> 📋 **Track progress in the master roadmap:** [`ROADMAP.md`](./ROADMAP.md) — Phase 4 references this doc. Codex updates the roadmap checkboxes as each step here completes.

 > **Delegation prompt for a coding agent.**
 > Implements the canonical `publish-packages.yml` workflow that publishes `@bytelyst/*` packages to the Gitea npm registry on every `v*` tag, and propagates it to all 20+ ByteLyst repos.

 > Companions:
 >
-> - [`HOSTINGER_GITEA_RUNNER_ROADMAP.md`](./HOSTINGER_GITEA_RUNNER_ROADMAP.md) — execution tracker.
-> - [`HOSTINGER_GITEA_ACT_RUNNER_SETUP.md`](./HOSTINGER_GITEA_ACT_RUNNER_SETUP.md) — the runner that executes this workflow.
+> - [`ROADMAP.md`](./ROADMAP.md) — execution tracker.
+> - [`ACT_RUNNER_SETUP.md`](./ACT_RUNNER_SETUP.md) — the runner that executes this workflow.

 ---

@ -354,7 +354,7 @@ CORP_SHA=$(curl -s -H "Authorization: token $(cat ~/.gitea_npm_token)" \
 1. **File:** `learning_ai_common_plat/.gitea/workflows/publish-packages.yml` with the Node image digest pinned (run `docker pull node:20-bookworm && docker inspect node:20-bookworm | grep sha256` to get the digest).
 2. **File:** `learning_ai_common_plat/scripts/sync-publish-workflow.sh` if going with Option B.
 3. **Secret:** confirm `GITEA_NPM_TOKEN` is set as a Gitea repo secret in `Settings → Secrets`. Document its value source (`~/.gitea_npm_token` on each machine).
-4. **Test:** the throwaway-package E2E from `HOSTINGER_GITEA_ACT_RUNNER_SETUP.md` §6 must pass, including the cross-Gitea SHA comparison.
+4. **Test:** the throwaway-package E2E from `ACT_RUNNER_SETUP.md` §6 must pass, including the cross-Gitea SHA comparison.
 5. **Commit + push** to both `origin` (GitHub) and `gitea` (whichever Gitea is locally reachable).
 6. **Add a SKILL doc** at `AI.dev/SKILLS/gitea-package-publishing.md` that references this workflow and the act_runner setup.

--- a/docs/devops/gitea-runner/README.md
+++ b/docs/devops/gitea-runner/README.md
@ -0,0 +1,37 @@
+# Gitea Actions Runner — Hostinger VM rollout
+
+This folder contains everything needed to set up the **canonical CI/CD pipeline** for `@bytelyst/*` package publishing: a self-hosted `act_runner` on the Hostinger Gitea, paired with a matching runner on the corp Mac local Gitea.
+
+## File map
+
+| File                                                         | Purpose                                                                                               | Audience               |
+| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | ---------------------- |
+| [`CODEX_DELEGATION_PROMPT.md`](./CODEX_DELEGATION_PROMPT.md) | 🎯 **Start here.** The bootstrap prompt to hand to Codex on the Hostinger VM + a one-liner.           | Human delegator        |
+| [`ROADMAP.md`](./ROADMAP.md)                                 | Master execution tracker. Phased checklist (P0 → P6) Codex updates with commit hashes as it executes. | Codex + human reviewer |
+| [`ACT_RUNNER_SETUP.md`](./ACT_RUNNER_SETUP.md)               | Implementation detail for installing `act_runner` on Hostinger VM. Referenced from roadmap P1–P3.     | Codex                  |
+| [`PUBLISH_WORKFLOW.md`](./PUBLISH_WORKFLOW.md)               | The actual `publish-packages.yml` workflow + propagation strategy. Referenced from roadmap P4–P5.     | Codex                  |
+| [`_PLAN_B_GITHUB_RUNNER.md`](./_PLAN_B_GITHUB_RUNNER.md)     | Alternative path (GitHub Actions self-hosted runner). Kept for reference; not used.                   | Reference only         |
+
+## One-liner to hand off
+
+```
+Read docs/devops/gitea-runner/CODEX_DELEGATION_PROMPT.md in learning_ai_common_plat, then execute the prompt within. Begin with P0.
+```
+
+## Why this lives in its own folder
+
+`docs/devops/` is filling up with multi-doc workstreams (Azure setup, KV rotation, single-VM deployment, E2EE, etc.). To prevent future roadmaps and delegation prompts from colliding with each other, each multi-doc workstream gets its own subfolder. Pattern to follow when you start a similar workstream:
+
+```
+docs/devops/<workstream-slug>/
+  README.md                       # this file — index
+  CODEX_DELEGATION_PROMPT.md      # paste-to-codex bootstrap
+  ROADMAP.md                      # phased checklist with checkboxes + commit hashes
+  <DETAIL_DOC_1>.md               # implementation detail
+  <DETAIL_DOC_2>.md
+  _PLAN_B_<alternative>.md        # discarded alternatives (underscore prefix = deprioritized)
+```
+
+## Architecture summary (1-paragraph)
+
+The same `v*` git tag pushed to two Gitea instances (corp Mac local + Hostinger) triggers each Gitea's own `act_runner` to build `@bytelyst/*` packages inside the **same pinned Docker image** (`node:20-bookworm@sha256:...`) from the **same lockfile**. Deterministic builds → byte-identical tarballs → matching SHA512 integrity → lockfiles portable across both registries. **No sync script. No GitHub Organization migration. No third-party billing entanglements.** See [`ROADMAP.md`](./ROADMAP.md) §🎯 Outcome for the invariant.
--- a/docs/devops/HOSTINGER_GITEA_RUNNER_ROADMAP.md
+++ b/docs/devops/HOSTINGER_GITEA_RUNNER_ROADMAP.md
@ -10,9 +10,9 @@
 >
 > **Detailed instructions** for each phase live in two companion docs — link from each phase. Don't repeat the details here; just track progress.
 >
-> - Runner install detail: [`HOSTINGER_GITEA_ACT_RUNNER_SETUP.md`](./HOSTINGER_GITEA_ACT_RUNNER_SETUP.md)
-> - Publish workflow detail: [`GITEA_PACKAGES_PUBLISH_WORKFLOW.md`](./GITEA_PACKAGES_PUBLISH_WORKFLOW.md)
-> - Plan B (GitHub Actions instead, not used): [`HOSTINGER_GITHUB_RUNNER_SETUP.md`](./HOSTINGER_GITHUB_RUNNER_SETUP.md)
+> - Runner install detail: [`ACT_RUNNER_SETUP.md`](./ACT_RUNNER_SETUP.md)
+> - Publish workflow detail: [`PUBLISH_WORKFLOW.md`](./PUBLISH_WORKFLOW.md)
+> - Plan B (GitHub Actions instead, not used): [`_PLAN_B_GITHUB_RUNNER.md`](./_PLAN_B_GITHUB_RUNNER.md)

 ---

@ -32,7 +32,7 @@ Total phases: **6** (P0 → P5) + **Review handoff (P6)**

 ### P0 — Pre-flight + environment verification

-> Detail: [§2 of runner setup doc](./HOSTINGER_GITEA_ACT_RUNNER_SETUP.md#2-pre-flight-checks-run-first-do-not-skip)
+> Detail: [§2 of runner setup doc](./ACT_RUNNER_SETUP.md#2-pre-flight-checks-run-first-do-not-skip)

 - [ ] **P0.1** All 10 pre-flight checks pass on Hostinger VM
  - Commit: _none (read-only)_
@ -49,7 +49,7 @@ Total phases: **6** (P0 → P5) + **Review handoff (P6)**

 ### P1 — Install `act_runner` on Hostinger VM

-> Detail: [§4 of runner setup doc](./HOSTINGER_GITEA_ACT_RUNNER_SETUP.md#4-installation)
+> Detail: [§4 of runner setup doc](./ACT_RUNNER_SETUP.md#4-installation)

 - [ ] **P1.1** Create `gitea-runner` user (idempotent; docker group)
  - Commit: _system change, not git_
@ -75,7 +75,7 @@ Total phases: **6** (P0 → P5) + **Review handoff (P6)**

 ### P2 — Smoke test (runner picks up jobs)

-> Detail: [§5 of runner setup doc](./HOSTINGER_GITEA_ACT_RUNNER_SETUP.md#5-smoke-test-basic--runner-picks-up-jobs)
+> Detail: [§5 of runner setup doc](./ACT_RUNNER_SETUP.md#5-smoke-test-basic--runner-picks-up-jobs)

 - [ ] **P2.1** Create branch `runner/gitea-smoke` with `.gitea/workflows/runner-smoke.yml`
  - Commit: `<sha7>`
@ -89,7 +89,7 @@ Total phases: **6** (P0 → P5) + **Review handoff (P6)**

 ### P3 — End-to-end validation (throwaway package + cross-Gitea byte-identical check)

-> Detail: [§6 of runner setup doc](./HOSTINGER_GITEA_ACT_RUNNER_SETUP.md#6-end-to-end-validation--proves-the-actual-publish-pipeline)
+> Detail: [§6 of runner setup doc](./ACT_RUNNER_SETUP.md#6-end-to-end-validation--proves-the-actual-publish-pipeline)

 - [ ] **P3.1** Create throwaway `@bytelyst/_runner-e2e-test` package on branch `runner/gitea-e2e`
  - Commit: `<sha7>`
@ -116,7 +116,7 @@ Total phases: **6** (P0 → P5) + **Review handoff (P6)**

 ### P4 — Implement publish-packages.yml (the real workflow)

-> Detail: [Publish workflow doc](./GITEA_PACKAGES_PUBLISH_WORKFLOW.md)
+> Detail: [Publish workflow doc](./PUBLISH_WORKFLOW.md)

 - [ ] **P4.1** Look up current `node:20-bookworm` digest from Docker Hub via `docker inspect` on Hostinger
  - Commit: _none_
@ -136,7 +136,7 @@ Total phases: **6** (P0 → P5) + **Review handoff (P6)**

 ### P5 — First real release through the new pipeline

-> Detail: [§4 of publish workflow doc](./GITEA_PACKAGES_PUBLISH_WORKFLOW.md#4-releasing-a-new-package-version-operator-workflow)
+> Detail: [§4 of publish workflow doc](./PUBLISH_WORKFLOW.md#4-releasing-a-new-package-version-operator-workflow)

 - [ ] **P5.1** Coordinate with human: which package to bump for the first real release? (Suggestion: lowest-risk one — `@bytelyst/errors` or similar with no consumers' tests depending on a version bump.)
  - Commit: _none (decision)_
@ -238,7 +238,7 @@ When you tick a checkbox, write the commit message like:
 chore(roadmap): mark P1.6 complete — act_runner systemd service active

 Service is running and journal shows "Polling for tasks". See
-docs/devops/HOSTINGER_GITEA_RUNNER_ROADMAP.md for the full tracker.
+docs/devops/gitea-runner/ROADMAP.md for the full tracker.
 ```

 When you fill in a commit hash field for a code change, use the **short SHA** (7 chars) of the commit that performed the work — **not** the SHA of the roadmap-update commit itself. Example:
--- a/docs/devops/gitea-runner/_PLAN_B_GITHUB_RUNNER.md
+++ b/docs/devops/gitea-runner/_PLAN_B_GITHUB_RUNNER.md
@ -1,7 +1,7 @@
 # Hostinger VM — GitHub Actions Self-Hosted Runner Setup

 > ⚠️ **PLAN B — not the recommended path.**
-> The canonical path uses **Gitea Actions** (which you already have configured in `.gitea/workflows/` across all repos). See [`HOSTINGER_GITEA_ACT_RUNNER_SETUP.md`](./HOSTINGER_GITEA_ACT_RUNNER_SETUP.md) for the recommended setup, and [`GITEA_PACKAGES_PUBLISH_WORKFLOW.md`](./GITEA_PACKAGES_PUBLISH_WORKFLOW.md) for the publish pipeline.
+> The canonical path uses **Gitea Actions** (which you already have configured in `.gitea/workflows/` across all repos). See [`ACT_RUNNER_SETUP.md`](./ACT_RUNNER_SETUP.md) for the recommended setup, and [`PUBLISH_WORKFLOW.md`](./PUBLISH_WORKFLOW.md) for the publish pipeline.
 >
 > Why this doc exists: it documents a fully valid alternative — a self-hosted GitHub Actions runner on the Hostinger VM. Keep this if you ever decide to make GitHub Actions the canonical CI driver (e.g., to take advantage of the GitHub Actions ecosystem). For now, Gitea Actions is simpler because:
 >