Onboarding a New Repo¶

Steps to bring a new repo into the magi platform ecosystem with all shared infrastructure in place from day one.

Prerequisites¶

New repo exists locally and on GitHub under rtsko/.
PLATFORM_VERSION is set to the current Ireul release tag.
pre-commit is installed locally.

Step 1: Copy the scaffold¶

# Copy all scaffold template files into the new repo root; replace repo-name before committing
cp -r /path/to/ireul/scaffold/new-repo/. /path/to/new-repo/

The scaffold provides:

File	Purpose
`mkdocs.yml`	MkDocs config template with hook wired up
`.pre-commit-config.yaml`	Pre-commit config pointing at Ireul
`docs/index.md`	Placeholder docs index

Step 2: Fetch the MkDocs hook and platform CSS¶

MkDocs requires hook files to be local. Neither the hook nor the platform CSS is committed to consumer repos; fetch both before running mkdocs serve locally. The Cloudflare Pages build command fetches them automatically.

# Fetch the hook and platform CSS from Ireul; neither is committed to the repo
mkdir -p hooks docs/stylesheets \
  && curl -fsSL -o hooks/config.py \
     https://raw.githubusercontent.com/${PLATFORM_REPO:-rtsko/ireul}/${PLATFORM_VERSION:-main}/mkdocs/hooks/config.py \
  && curl -fsSL -o docs/stylesheets/platform.css \
     "${DOCS_CSS_URL:-https://ireul.pages.dev/platform.css}"

The hook detects docs/stylesheets/platform.css and injects it as a local extra_css path. This prevents the instant-navigation CSS flash that occurs when the stylesheet is loaded from an external URL. A repo that uses a different stylesheet sets DOCS_CSS_URL to its own source URL and the build command fetches that instead.

Add both fetched directories to .gitignore:

# Exclude fetched hook and CSS from version control; both are re-fetched at build time
echo "hooks/" >> .gitignore
echo "docs/stylesheets/platform.css" >> .gitignore

Step 3: Copy lint configs¶

# Copy lint configs to repo root and lint/ directory so pre-commit hooks can resolve them
cp /path/to/ireul/lint/.editorconfig .editorconfig
mkdir -p lint
cp /path/to/ireul/lint/ruff.toml lint/ruff.toml
cp /path/to/ireul/lint/yamllint.yml lint/yamllint.yml

Step 4: Update mkdocs.yml¶

Replace the repo-name placeholder in mkdocs.yml:

# Set repo identity in mkdocs.yml; runtime values like site_url and CSS URL come from environment variables
site_name: "your-repo-name"
repo_url: "https://github.com/rtsko/your-repo-name"

Leave site_url, edit_uri, and extra_css empty. Those are injected via DOCS_CSS_URL and other environment variables at build time.

Step 5: Update .pre-commit-config.yaml¶

Set rev: to the current PLATFORM_VERSION:

# Pin pre-commit hook source to the current PLATFORM_VERSION tag for reproducible lint environments
repos:
  - repo: https://github.com/rtsko/ireul
    rev: v0.1.0  # replace with current PLATFORM_VERSION
    hooks:
      - id: ruff-lint
      - id: ruff-format
      - id: yamllint

Step 6: Add environment variables¶

Add these to .env.example:

# /─[ PLATFORM ]────────────────────────────────────────────────────────
PLATFORM_REPO=rtsko/ireul   # optional — set to your fork if you forked Ireul (owner/repo)
PLATFORM_VERSION=v0.1.0     # required — pin to current Ireul release tag

# /─[ DOCS ]────────────────────────────────────────────────────────────
DOCS_CSS_URL=               # required — Ireul stylesheet URL from Cloudflare Pages
DOCS_SITE_NAME=             # required — display name shown in the docs header and browser tab

Step 7: Install pre-commit hooks¶

# Install all pre-commit hooks into the local git hooks directory so they run on every commit
pre-commit install

Verify everything passes before the first commit:

# Run all pre-commit hooks against the full repository to confirm a clean baseline before committing
pre-commit run --all-files

Checklist¶

[ ] Scaffold copied
[ ] hooks/ added to .gitignore
[ ] hooks/config.py fetched for local development
[ ] Lint configs in place (lint/ruff.toml, lint/yamllint.yml, .editorconfig)
[ ] mkdocs.yml repo-name placeholder replaced
[ ] .pre-commit-config.yaml pinned to PLATFORM_VERSION
[ ] .env.example has PLATFORM_REPO, PLATFORM_VERSION, DOCS_CSS_URL, DOCS_SITE_NAME
[ ] pre-commit install run
[ ] pre-commit run --all-files passes