← knowledge.oriz.in

Runbooks index — every operational procedure

index indexrunbookmeta

Runbooks index

Operational procedures for the family. Each entry is a type: runbook concept file with numbered commands and dashboard URLs.

A runbook is a sequence of human-actionable commands that a person (or a sufficiently authenticated agent) can run to accomplish a specific operational outcome. Runbooks are distinct from process files (which describe how the team operates) and decision files (which lock in what we chose).

Active runbooks

File When to run Run by
auth-setup.md First-time setup of a new machine, or after a multi-tool token rotation User (interactive browser flows)
clean-install.md Bootstrap the entire family on a fresh machine — recursive clone + pnpm install loop User or agent (one-shot)
add-new-site-to-family.md Adding a new oriz-<name> site as a submodule User (some steps), agent (most)
add-new-extension.md Adding a new Chrome / Firefox / Edge extension as a submodule User (some steps), agent (most)
add-new-decision.md The OKF self-update workflow — capturing a chat decision into the knowledge bundle Agent (always)
rotate-leaked-secret.md When a secret has entered any transcript, screenshot, or untrusted log User (revoke + reissue), agent (verify)
bump-submodule-pointer.md After landing a feature in a submodule, bumping the master pointer Agent (always)
rename-repo.md Renaming a repo to its role-suffixed slug (-site / -ext / -vsc-ext / etc.) and threading the rename through .gitmodules, package.json, README, and the master pointer Agent (most), user (push + Cloudflare Pages reconnect)
One-shot bulk migration of all 11 site repos to the -site suffix (driven by scripts/rename-sites-to-suffix.sh) User-supervised (script pauses between sites)
apply-per-site-ci.md Land the per-repo CI scaffold (CI lint/typecheck/build + CF Pages deploy + GH Pages mirror + Dependabot + CodeQL + CodeRabbit + SonarCloud + Biome) into each of the 11 site submodules and 6 package submodules from templates/per-site-ci/ Agent (copy + commit), user (CF Pages project creation + secret setup + push)
restic-backup-setup.md Set up the weekly restic → Backblaze B2 backup loop in a data-bearing repo (init repo, add weekly workflow, restore drill, retention policy) Agent (copy + commit), user (one-shot restic init + first gh workflow run)
sync-env-example-to-all-repos.md Add / remove / rename a family-wide env var: edit master templates/.env.example, run scripts/sync-env-example.sh, commit + push every touched submodule + bump master pointers, verify with scripts/verify-env-example-sync.sh Agent (run script + commit), user (push, especially for new keys)
set-github-org-level-secrets.md Pull a secret value from Doppler and set it at the chirag127 ORG level for GitHub Actions (gh secret set --org chirag127 --visibility all); used after adding a new key to templates/.env.example, after a rotation, and on the quarterly audit Agent (script run + verify), user (initial Doppler write)
add-package-to-catalog.md After publishing a new chirag127/*-npm-pkg repo, ensure it appears in packages.oriz.in catalog (auto-discovery handles 95%; this documents the speed-up repository_dispatch + group keyword) Agent (config), user (PAT setup once)
cf-dns-add-api-subdomain.md Wire a new <sub>.api.oriz.in CNAME → chirag127.github.io (DNS-only / grey cloud) via scripts/cf-dns-set-api-cnames.mjs. Idempotent. Includes DoH verification + GH Pages cert checklist. Agent (script + verify), user (set Pages custom domain in target repo)
migrate-ci-platform.md Plan-B runbook: if GitHub Actions becomes unusable, translate every workflow to GitLab CI or CircleCI. Mirror cron keeps source on 4 hosts already. User + agent
mirror-cron-prep.md Pre-flight for the old 4-host Friday cron (superseded by mirror-all-hosts-setup.md — kept for reference) User (legacy)
mirror-all-hosts-setup.md Current one-time setup for the 9-host automatic mirror (GitLab, Codeberg, Bitbucket, GitFlic, Azure DevOps, NotABug, GitGud, RocketGit, Radicle): token + keypair generation, pre-creating repos on the 8 HTTPS hosts, storing org-level secrets, dry-run + first real run verification. See decisions/ops/mirror-to-9-popular-alternatives-2026-06-28.md User (token gen), agent (scripted repo creation + verify)
install-and-bootstrap.md Fresh-clone OR existing-clone-update for the umbrella workspace — recursive submodule init + recursive pnpm install. THE canonical install procedure. User (any session start), agent (any session start)
npm-publish-token-setup.md First-time npm Granular Access Token setup with bypass-2FA toggles for publish + unpublish; used by every @chirag127/* package release User (one-time token gen), agent (per-publish flow)
build-distributable.md Build PWA + Android APK (Bubblewrap TWA) + desktop EXE/dmg/AppImage (Tauri) from a single app via @chirag127/astro-distribute Agent (CI), user (signing key setup)
razorpay-end-to-end-setup.md After Razorpay signup: generate TEST API keys, verify the 4 pre-created plans, add webhook with 9 events, create 4 promo codes (FOUNDER50/LAUNCH30/BLOG20/STUDENT50), wire into @chirag127/astro-billing, E2E test with test card 4111… via ngrok, then flip to LIVE. User (dashboard clicks + push), agent (integration code in future task)
migrate-okf-to-new-version.md Placeholder for when OKF v0.1 → v0.2 happens Agent + user
dependabot-notification-tuning.md Kill Dependabot email noise without disabling alerts. Phase 1 user UI settings + Phase 2 per-repo dependabot.yml batching sweep. Drops email volume ~90%. User (UI clicks), agent (sweep)
github-apps-audit-2026-06-22.md One-shot audit of 33 installed GitHub Apps on chirag127. 5 KEEP / 20 REMOVE-recommended / 8 REVIEW. Uninstall is manual (no API). User (uninstall clicks), agent (audit only)
free-hosting-providers/ Catalog of every free-tier hosting provider vetted under the no-card-on-file rule. 8 sub-files covering static sites / web services / serverless functions / databases / object storage / image CDN / queues + pub-sub / monitoring. KEEP / EVALUATE / DROP per provider. Re-verify quarterly. Agent (research + write), user (re-verify on quarterly audit)
visual-audit-2026-06-22.md Playwright-driven visual audit of all 5 local apps + 19 API subdomains. Captures 29 screenshots (desktop + mobile), classifies each surface against Rule-13 brief, lists P0/P1/P2 fixes. home-4321 broken, mmi.api 404, 14/19 API subdomains render bare README HTML (no brand, no live data preview). currency.api is the gold-standard template. Agent (re-run on every deploy)
git-upstream-merge-private-fork.md Maintain a private organization repo of a public Chrome extension and sync upstream releases User + Agent

Where runbooks sit relative to the rest

Cross-links