moonweb-site/SPEC.md

# moonweb.org — Specification

Status: Concept finalized. This document defines *what* gets built. See `PLAN.md` for *how and in what order*.

## 1. Purpose

A personal homelab hub consisting of a central index (`hub`) and several themed static sites, replacing the current unstructured presentation of infrastructure, smart home projects, and GitHub repos. cv (stefankoelle.de) remains external, linked from the hub and site-switcher.

## 2. Sitemap

```
moonweb-site (monorepo)
├── hub/         → hub.moonweb.org        Central index & gateway
├── infra/       → infra.moonweb.org      System architecture / stack overview
├── smarthome/   → smarthome.moonweb.org  What the homelab actually runs, and why
├── code/        → code.moonweb.org       Curated GitHub catalog
└── retro/       → retro.moonweb.org      Physical retro hardware collection

outside the monorepo, untouched:
├── stefankoelle.de          CV, career, personal (extern gehostet)
├── www.moonweb.org          finished, no overlap (2001-style internet time capsule)
├── 28k8.moonweb.org         90s BBS/scene archive, separate approach, may migrate later (undecided)
└── home.moonweb.org         Authelia-protected homelab dashboard/control plane (not part of this site set)
```

Apex domain `moonweb.org` currently redirects to `www.moonweb.org`. This stays as-is for now; a later redirect to `hub.moonweb.org` is possible but out of scope for this build. Cloudflare Free-Tier limits to 5 Pages projects per repository, which is why cv (stefankoelle.de) stays external.

## 3. Domain purposes

| Domain | Purpose | Tone |
|---|---|---|
| hub | Gateway, links to everything, one-line description per destination | Minimal |
| infra | Shallow, structured overview of the stack: Proxmox (PVE + pve2), Synology DS918+, VLANs, Fritz!Box mesh, SSO, plus how I work (OpenCode/OpenClaw dev environment) | Reference, high-level only |
| smarthome | Why the homelab exists — what's actually running on `home.moonweb.org` as smart home: sensors, automation, calendar/contacts sync, dashboards, media | Project storytelling |
| code | Curated, sorted GitHub catalog — overview only, always linking out to GitHub | Portfolio |
| retro | Physical retro hardware collection (not software/demos — that's 28k8's domain) | Simple, factual |

## 4. Design system

### 4.1 Header-consistent, content-flexible principle

- **Header is identical** across infra/smarthome/code/retro: site-switcher (hub · infra · smarthome · code · retro), domain accent color, consistent branding.
- **Overview (index) pages** use a shared card-grid layout (reference: current `home.moonweb.org` — banner header, grouped card sections, clean sans-serif, generous whitespace, light theme only, no heavy JS).
- **Detail/sub-pages** keep the same header but may use a freer layout below it (reference: `/ledmatrix/` on stefankoelle.de today — pin tables, API docs, photos in free layout instead of a rigid card grid).

Note: cv (stefankoelle.de) is external and uses its own independent design — it does not follow this principle.

### 4.2 Accent colors per domain

| Domain | Accent |
|---|---|
| hub | Neutral blue |
| infra | Grey-blue |
| smarthome | Teal |
| code | Violet |
| retro | Own accent, still clean card-grid (no 90s styling — that belongs to 28k8) |

### 4.3 URL convention

`domain/slug/` — lowercase, hyphenated, trailing slash, matching the existing stefankoelle.de pattern (e.g. `/ledmatrix/`) so future detail pages stay consistent even if content later migrates between sites. cv (stefankoelle.de) follows its own existing URL patterns and is not part of this convention.

## 5. Content depth rules (per domain)

| Domain | Detail pages? | Rule |
|---|---|---|
| smarthome | Yes, when there's enough content | Index shows how the smart home is structured; a topic gets a detail page immediately if enough data exists — otherwise it's mentioned in the overview only, no placeholder required |
| code | Never | Overview cards + link to GitHub only. No duplicating README content. |
| infra | Rarely | Deliberately shallow — most of the raw material is sensitive (see §6) |
| retro | Yes, but minimal | Topic is still immature; create only a rudimentary overview, don't over-invest time |

General rule across all domains: **if content is too thin for a good detail page, skip the detail page — don't create a placeholder.**

Note: cv (stefankoelle.de) is external and not subject to these rules.

## 6. Infra content redaction rule

Because infra must stay shallow and public-safe:

- **Allowed:** architecture level — Proxmox + Synology + Docker host, VLAN concept without concrete internal IP plans, which service types run, which tools are used.
- **Not allowed:** concrete IP addresses, WireGuard keys/preshared keys, passwords, internal hostnames that allow inference, backup targets with credentials.

This rule applies to any domain but is most relevant for infra, since the source documents (e.g. Heimnetzwerk-Final-v3.2, GL_Flint2_Final_v2) currently contain real IPs and keys that must be actively stripped during migration. cv (stefankoelle.de) is maintained separately and not subject to this rule.

## 7. Language

All five sites (hub, infra, smarthome, code, retro) are written **entirely in English**. Existing German source documents are translated once during migration via a single AI-assisted pass — not a recurring process. New `.moonweb.yml` metadata and generated content are authored in English from the start. cv (stefankoelle.de) remains in its existing language.

## 8. GitHub automation (code.moonweb.org)

Each GitHub project repo gets a `.moonweb.yml` in its root:

```yaml
title: "MVG Departures"
category: code          # code | smarthome | infra
subcategory: "Web Apps" # drives grouping on code.moonweb.org
status: active
stack: [Python, FastAPI]
hosted_on: "Docker Host Debian (PVE)"
summary: "Compact MVG/S-Bahn departure monitor with configurable stations."
repo_url: "https://github.com/skoelle/mvg-departures"
```

A local aggregator script reads `.moonweb.yml` from all repos via the GitHub API, an AI pass turns the raw YAML into readable card copy, and the result is committed into `code/_data/repos.json` inside the monorepo. This runs manually, on demand — no scheduled automation for now. cv (stefankoelle.de) is not included in this automation.

## 9. Content maintenance

- infra, smarthome, retro: **fully manual**, edited in vim, committed via git push. No automation.
- code: the only automated piece is the GitHub aggregator described in §8.
- No "last updated" timestamps are shown anywhere — the goal is that content is simply kept current, not that staleness is displayed.
- No analytics/tracking of any kind on any of the five sites.
- Images/assets live versioned directly in the monorepo (no external asset host).
- cv (stefankoelle.de): maintained separately, linked from hub/site-switcher.

## 10. Repository structure

```
moonweb-site/
├── hub/
├── infra/
├── smarthome/
├── code/
│   └── _data/repos.json     # populated by the GitHub aggregator
├── retro/
├── shared/
│   ├── _includes/
│   │   ├── base.njk          # shared header + footer layout
│   │   └── card-grid.njk     # card-grid template
│   ├── base.css              # shared CSS variables and layout
│   └── theme-*.css           # one accent color file per domain
├── scripts/
│   └── github-aggregator/    # reads .moonweb.yml from all repos
├── DESIGN.md                 # initial concept and design decisions
├── SPEC.md                   # what gets built (this document)
├── PLAN.md                   # how and in what order
├── TODO.md                   # open items and workflow
└── .github/workflows/
    └── build-deploy.yml      # builds all sites, deploys each to its Cloudflare Pages project
```

Note: `cv/` (stefankoelle.de) is hosted externally and linked from hub/site-switcher — it is not part of this monorepo (Cloudflare Free-Tier limits to 5 Pages projects per repository).

## 11. Technical stack

- **Static site generator:** Eleventy (11ty) — markdown/YAML-first, minimal JS, `_data` folders map directly onto the `.moonweb.yml` aggregator output, low maintenance for five sites at this scale.
- **Build:** entirely in GitHub Actions.
- **Deploy:** Cloudflare Pages — five separate Pages projects (one per public domain: hub, infra, smarthome, code, retro), since Cloudflare Pages binds one custom-domain set per project. One shared GitHub Actions workflow builds all five sites and deploys each output folder to its respective Pages project.
- **Cloudflare Free-Tier limit:** Max 5 Pages projects per repository — cv (stefankoelle.de) stays external to avoid hitting this limit.
- **Runtime:** fully static, no server-side code, no containers for the website itself (distinct from the actual homelab services running on the Docker host).
- **DNS:** already on Cloudflare — no additional setup step needed for Pages custom domains.
- **Local preview:** Eleventy's built-in dev server with live reload, run per-site (`npm run dev:<site>`) before any commit.

## 12. Explicitly out of scope for this build

- Migrating `/ledmatrix/` (and any other existing stefankoelle.de sub-pages) into smarthome — stays linked externally for now, migrates in a later phase.
- Migrating 28k8.moonweb.org into the monorepo — undecided, revisit later, likely never.
- Any Perplexity-backchannel mechanism (website content reusable inside this project) — deferred, no time invested now.
- Analytics of any kind.
- Automated content generation/translation pipelines beyond the one-time GitHub aggregator for code and the one-time translation pass during migration.
- Porting stefankoelle.de into the monorepo — stays external (Cloudflare Free-Tier limits to 5 Pages projects per repository).