MakerFLOSS/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a **documentation-only repository** for the MakerFLOSS initiative at Orange Makerspace — a bi-weekly FLOSS jam-session community focused on self-hosted, open-source infrastructure. There is no build system, test suite, or application code.

## Working Norms

From `notes/todo/2026-04-14-todo.md`:

- **Language**: English for code, docs, commits (meeting notes may be in Danish)
- **Git**: Trunk-based development, feature branches, simple commit messages
- **Environments**: Containerized and reproducible
- **Hardware**: All setups documented with README + labeled physically
- **AI**: Allowed but reviewed; no secrets in commits
- **Decisions**: Lightweight markdown decision logs
- **License**: FLOSS by default
- **Filenames**: ASCII lowercase, kebab-case (`like-this.md`), English regardless of content language. Dated docs use an ISO prefix joined with a hyphen: `YYYY-MM-DD-label.md`. Hostnames are the exception — `docs/hardware/*.md` must equal the host's `hostname` (enforced by `scripts/gen_overview.py`).
- **Hardware identifiers**: `<kind-abbrev><NN>` — 2-digit, unique per kind (`srv`, `sw`, `pp`, `pdu`, `ups`, `shf`). Grouping (`cluster:`) lives in frontmatter, not the name. Full scheme: `docs/guides/hardware-naming-scheme.md`.

## Repository Structure

```
docs/             # everything here is built and shipped to docs.makerfloss.eu
  hardware/       # auto-indexed per-host frontmatter (srv01..srv05, makerfloss.eu)
  services/       # auto-indexed per-service frontmatter (docs, forgejo, …)
  infrastructure/ # labdesign, VPS/DNS, etc.
  presentations/  # Marp decks (build-slides.sh)
notes/            # repo-only working material, not built
  meetings/       # meeting notes (Danish allowed)
  todo/           # task lists, working norms, wishlist, services
  dev/            # internal plans/ and specs/
  communications/ # community comms artifacts (Facebook posts, etc.)
sandbox/          # scratch / pipeline fixtures (e.g. test-mermaid.md)
```

## Infrastructure

The MakerFLOSS infrastructure is managed externally via the **AnsibleBaobabV4** Ansible project (hosted at `forgejo.nyumbani.baobab.band/sjat/AnsibleBaobabV4`). Key facts:

- **VPS**: `88.99.32.236`, SSH on port `7576`
- **Forgejo** (self-hosted git forge): `https://forgejo.makerfloss.eu`, SSH on port `7577`
- **Reverse proxy**: Traefik with automatic Let's Encrypt TLS
- **DNS**: `makerfloss.eu` via Gandi.net, managed declaratively through Ansible (`play_dns.yml --limit makerfloss`)
- **DNS records must never be edited directly** in the Gandi panel — always edit `host_vars/makerfloss.yml` in AnsibleBaobabV4

Clone via Forgejo SSH:
```bash
git clone ssh://git@forgejo.makerfloss.eu:7577/<user>/<repo>.git
```