From fdab93e829bedcc5065c32e11102e6ecbab220ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Lohrer?= Date: Tue, 28 Apr 2026 07:30:44 +0200 Subject: [PATCH] docs: top-level-rollen geklaert + status-stempel README/STATUS/HANDOFF/CLAUDE jeweils ein rollensatz oben: - README = aussenseite - STATUS = logbuch (stand + erledigt-chronologie) - HANDOFF = konventions-handbuch (workflows + stolperfallen) - CLAUDE.md = session-einstieg HANDOFF erhaelt zusaetzlich eine Single-Source-of-Truth-sektion, damit klar ist welche fakten wo gepflegt werden. README-linkliste auf 3 specs eingedampft (SPA, pipeline, multilingual) und auf das plan-archiv verlinkt statt einzelplaene. CLAUDE.md verlinkt zusaetzlich die prerender-snapshot-spec mit kennzeichnung. STATUS.md verzeichnis-baum spiegelt das archiv wider. Wiki-entwuerfe + redaktions-doku + github-ci-setup-doku haben explizite status-stempel (eingefroren / schnappschuss / aktuell-aber-zu-ersetzen), damit man nicht mehr raten muss. Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 7 ++++++- README.md | 12 ++++++------ docs/HANDOFF.md | 13 +++++++++++++ docs/STATUS.md | 8 ++++++-- docs/github-ci-setup.md | 2 ++ docs/redaktion-bild-metadaten.md | 2 ++ docs/wiki-draft-nostr-image-metadata.md | 2 +- docs/wiki-entwurf-nostr-bild-metadaten.md | 2 +- 8 files changed, 37 insertions(+), 11 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 5fba03a..de57275 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,5 +1,9 @@ # CLAUDE.md — Einstieg für Claude-Sessions +> **Rolle dieses Dokuments:** Session-Einstieg — Lese-Reihenfolge, +> Tonfall, kritische Fallstricke. Logbuch in [`docs/STATUS.md`](docs/STATUS.md), +> Konventionen in [`docs/HANDOFF.md`](docs/HANDOFF.md). + Dieser Einstieg ist für Claude-Code-Sessions gedacht. Für den inhaltlichen Projektstand siehe [`docs/STATUS.md`](docs/STATUS.md) und [`docs/HANDOFF.md`](docs/HANDOFF.md). @@ -93,7 +97,7 @@ wird von der Pipeline ignoriert. | `publish/src/` | Deno-Publish-Pipeline (Deno-Tasks in `publish/deno.jsonc`) | | `publish/tests/` | Deno-Tests für die Pipeline | | `docs/superpowers/specs/` | Produktdesigns, Konventionen | -| `docs/superpowers/plans/` | Implementierungspläne (alle erledigt) | +| `docs/superpowers/plans/archive/` | Umgesetzte Implementierungspläne (Geschichte) | | `scripts/deploy-svelte.sh` | FTPS-Deploy | ## Quick-Links @@ -102,4 +106,5 @@ wird von der Pipeline ignoriert. - [Produktspezifikation Publish-Pipeline](docs/superpowers/specs/2026-04-15-publish-pipeline-design.md) - [Bild-Metadaten-Konvention](docs/superpowers/specs/2026-04-16-image-metadata-convention.md) - [Multilingual-Design](docs/superpowers/specs/2026-04-21-multilingual-posts-design.md) +- [Prerender-Snapshot-Design](docs/superpowers/specs/2026-04-21-prerender-snapshot-design.md) (Entwurf, eingefroren) - [Repo-Workflow-Skill](.claude/skills/joerglohrerde-workflow.md) (ausführlicher, mit Kommandos) diff --git a/README.md b/README.md index b3b6c6b..719882d 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,10 @@ # joerg-lohrer.de +> **Rolle dieses Dokuments:** Außensicht — was ist das Repo, wie funktioniert +> es grob, wo geht's weiter. Für interne Arbeit siehe +> [`docs/STATUS.md`](docs/STATUS.md) (Logbuch) und +> [`docs/HANDOFF.md`](docs/HANDOFF.md) (Konventionen, Workflows). + Persönliche Webseite. Nach einer Transition von einer Hugo-basierten, statischen Seite läuft `joerg-lohrer.de` jetzt als SvelteKit-SPA, die Blog-Posts live aus signierten Nostr-Events (NIP-23, `kind:30023`) rendert. @@ -45,13 +50,8 @@ Identität und Assets: - 🤖 **Claude-Einstieg:** [`CLAUDE.md`](CLAUDE.md) (Agent-Konventionen, Deploy-Falle, Commit-Stil) - 📐 **SPA-Spec:** [`docs/superpowers/specs/2026-04-15-nostr-page-design.md`](docs/superpowers/specs/2026-04-15-nostr-page-design.md) - 📐 **Publish-Pipeline-Spec:** [`docs/superpowers/specs/2026-04-15-publish-pipeline-design.md`](docs/superpowers/specs/2026-04-15-publish-pipeline-design.md) -- 📐 **Bild-Metadaten-Konvention:** [`docs/superpowers/specs/2026-04-16-image-metadata-convention.md`](docs/superpowers/specs/2026-04-16-image-metadata-convention.md) - 📐 **Multilinguale Posts:** [`docs/superpowers/specs/2026-04-21-multilingual-posts-design.md`](docs/superpowers/specs/2026-04-21-multilingual-posts-design.md) -- 🛠 **SvelteKit-SPA-Plan:** [`docs/superpowers/plans/2026-04-15-spa-sveltekit.md`](docs/superpowers/plans/2026-04-15-spa-sveltekit.md) (35 Tasks, erledigt) -- 🛠 **Publish-Pipeline-Plan:** [`docs/superpowers/plans/2026-04-16-publish-pipeline.md`](docs/superpowers/plans/2026-04-16-publish-pipeline.md) (24 Tasks, erledigt) -- 🛠 **Multilingual 1/3 — Pipeline:** [`docs/superpowers/plans/2026-04-21-multilingual-posts-pipeline.md`](docs/superpowers/plans/2026-04-21-multilingual-posts-pipeline.md) (10 Tasks, erledigt) -- 🛠 **Multilingual 2/3 — SPA-Auflösung:** [`docs/superpowers/plans/2026-04-21-multilingual-posts-spa.md`](docs/superpowers/plans/2026-04-21-multilingual-posts-spa.md) (8 Tasks, erledigt) -- 🛠 **Multilingual 3/3 — UI-i18n:** [`docs/superpowers/plans/2026-04-21-multilingual-posts-i18n.md`](docs/superpowers/plans/2026-04-21-multilingual-posts-i18n.md) (11 Tasks, erledigt) +- 🗄 **Plan-Archiv:** [`docs/superpowers/plans/archive/`](docs/superpowers/plans/archive/) (alle umgesetzten Pläne als Geschichte) - 🤖 **Claude-Workflow-Skill:** [`.claude/skills/joerglohrerde-workflow.md`](.claude/skills/joerglohrerde-workflow.md) ## Branches diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index 085feac..8cb3d3a 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -1,8 +1,21 @@ # Handoff — Nächste Session +> **Rolle dieses Dokuments:** Konventions-Handbuch — wie hier gearbeitet +> wird (Posts, Übersetzungen, Deploys, Stolperfallen). Aktueller Stand +> steht in [`STATUS.md`](STATUS.md), Außensicht in [`../README.md`](../README.md). + Du (Claude, nächste Session) oder ich (Jörg, später) kommen hier zurück. Dieses Dokument sagt: was ist der Zustand, was wartet, wo liegen die Fäden. +## Single Source of Truth + +Damit nichts an mehreren Stellen pflegen werden muss: + +- **Live-URLs, Setup-Stand, Erledigt-Chronologie** → [`STATUS.md`](STATUS.md). +- **Frontmatter-Konventionen, Workflows, Stolperfallen** → dieses Dokument. +- **Spec-Liste** → `docs/superpowers/specs/`. README und CLAUDE.md + verlinken nur die für ihre Zielgruppe relevanten. + ## Zustand (Details in `STATUS.md`) **Cutover + Reimport 2026-04-18, Mehrsprachigkeit live seit 2026-04-21.** diff --git a/docs/STATUS.md b/docs/STATUS.md index 9cd8dcd..71d2975 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -1,5 +1,8 @@ # Projekt-Status: joerg-lohrer.de → Nostr-basierte SPA +> **Rolle dieses Dokuments:** Logbuch — aktueller Stand und Erledigt-Chronologie. +> Konventionen und Workflows stehen in [`HANDOFF.md`](HANDOFF.md). + **Stand:** 2026-04-21 (Mehrsprachigkeit live) ## Kurzfassung @@ -70,8 +73,9 @@ joerglohrerde/ │ ├── wiki-draft-nostr-image-metadata.md │ ├── github-ci-setup.md │ └── superpowers/ -│ ├── specs/ # SPA, Publish-Pipeline, Bild-Metadaten, Multilingual -│ └── plans/ # Alle Pläne erledigt (SPA, Pipeline, 3× Multilingual) +│ ├── specs/ # SPA, Publish-Pipeline, Bild-Metadaten, Multilingual, Prerender (Entwurf) +│ └── plans/ +│ └── archive/ # Umgesetzte Pläne (Geschichte) + eingefrorener Prerender-Plan ├── .github/workflows/ # publish.yml (Forgejo→GitHub Push-Mirror-Trigger) ├── .claude/ │ ├── skills/ # Repo-spezifischer Claude-Skill diff --git a/docs/github-ci-setup.md b/docs/github-ci-setup.md index cbee542..129723f 100644 --- a/docs/github-ci-setup.md +++ b/docs/github-ci-setup.md @@ -1,5 +1,7 @@ # GitHub-CI-Setup für die Publish-Pipeline +**Status:** Aktuell genutzt; mittelfristig zu ersetzen durch self-hosted CI (siehe `HANDOFF.md` → Option D). + **Kontext:** Das primäre Repo liegt in **Forgejo** (self-hosted). Für CI nutzen wir GitHub als **Push-Mirror-Ziel**, weil Forgejo keine Woodpecker-Integration hat. GitHub Actions triggert automatisch bei Push auf `main` mit Änderungen diff --git a/docs/redaktion-bild-metadaten.md b/docs/redaktion-bild-metadaten.md index c1f131c..3cde753 100644 --- a/docs/redaktion-bild-metadaten.md +++ b/docs/redaktion-bild-metadaten.md @@ -1,5 +1,7 @@ # Redaktion: Bild-Metadaten-Durchgang +**Status:** Schnappschuss vom 2026-04-18 — als Hilfsmittel für die Migrations-Sitzung erstellt, kein laufender Workflow. Bleibt als Referenz erhalten. + **Zweck:** 91 Bilder in 18 Posts visuell prüfen und Alt-Texte, Lizenzen, Autor:innen-Angaben gegen das echte Bild abgleichen. **Arbeitsweise:** diff --git a/docs/wiki-draft-nostr-image-metadata.md b/docs/wiki-draft-nostr-image-metadata.md index 2ba9f63..b766509 100644 --- a/docs/wiki-draft-nostr-image-metadata.md +++ b/docs/wiki-draft-nostr-image-metadata.md @@ -1,6 +1,6 @@ # Structured Image Metadata for Markdown-Sourced Nostr Long-Form Content -**Status:** Working draft — a practice convention, not (yet) a NIP. +**Status:** Frozen 2026-04-25 — finalised draft for external publication (NIP proposal / nostrbook.dev). Until published, this in-repo copy serves as a reference and historical record. Practice convention, not (yet) a NIP. **Scope:** Authors who maintain Markdown long-form posts (`kind:30023`, NIP-23) in a git repository and publish them to Nostr via a build pipeline. The convention defines how image metadata (author, license, source, alt text, caption) lives in the repository, how it becomes `imeta` tags (NIP-92) in the event, and how to round-trip between the two. **Goal:** Zero data loss between repository and event. Human-readable in raw Markdown. Machine-readable in the published event. Safe defaults against accidental misattribution. diff --git a/docs/wiki-entwurf-nostr-bild-metadaten.md b/docs/wiki-entwurf-nostr-bild-metadaten.md index d0a6dd2..6e48436 100644 --- a/docs/wiki-entwurf-nostr-bild-metadaten.md +++ b/docs/wiki-entwurf-nostr-bild-metadaten.md @@ -1,6 +1,6 @@ # Strukturierte Bild-Metadaten für Markdown-basierte Nostr-Langform-Beiträge -**Status:** Arbeitsentwurf — eine Praxis-Konvention, (noch) kein NIP. +**Status:** Eingefroren am 2026-04-25 — fertiger Entwurf für externe Veröffentlichung (NIP-Proposal / nostrbook.dev). Solange nicht publiziert, dient diese Repo-Kopie als Referenz und Geschichts-Dokument. Praxis-Konvention, (noch) kein NIP. **Scope:** Eine Inline-Markdown-Konvention zur Bildattribution (Urheber, Lizenz, Quelle, Bearbeitung), die in jedem Markdown-Editor direkt nutzbar ist und sich verlustfrei auf NIP-92-`imeta`-Tags in `kind:30023`-Events abbilden lässt. **Ziel:** Ein einheitliches, menschlich lesbares und maschinell parsbares Attributions-Format für Bilder in Nostr-Langform-Beiträgen. TULLU-BA-konform. Zero-Tool: funktioniert ohne Build-Pipeline. Zero-Loss: bidirektional konvertierbar zu `imeta`-Tags, sobald Publishing dazukommt.