Restructure repository into administration and website areas

administration/docs/brainstorms/2026-03-03-dom-json-wysiwyg-sync-brainstorm.md

@@ -0,0 +1,43 @@
+---
+date: 2026-03-03
+topic: dom-json-wysiwyg-sync
+---
+
+# DOM to JSON + WYSIWYG Sync
+
+## What We're Building
+A content workflow for this static site that starts with DOM-to-JSON extraction and then enables inline visual editing. The immediate goal is a JSON file generated from the current HTML snapshot that captures:
+- visible page text
+- page metadata (`title`, description, Open Graph/Twitter meta)
+- image content (`img src` and `alt`)
+
+The JSON should preserve subtopics and be structured by DOM context so it maps cleanly to the existing page. The follow-up goal is a lightweight WYSIWYG editor that lets humans change text directly in the page and update image `src`/`alt`, with synchronization between HTML and JSON.
+
+## Why This Approach
+The chosen direction prioritizes low-friction adoption in an existing static snapshot where editors still work directly in HTML. A DOM-to-JSON first pass minimizes upfront modeling effort and captures the current content state quickly. Then, a WYSIWYG layer provides direct manipulation while preserving visual context.
+
+YAGNI rationale: avoid building a full CMS or strict schema-first localization system now. Start with extraction and practical editing primitives, then evolve only if editorial complexity requires it.
+
+## Key Decisions
+- Output format: Nested JSON with subtopics.
+- Extraction scope: Visible page text plus metadata (title/description/Open Graph/Twitter).
+- Key organization: DOM-first grouping with section-based top-level subtopics.
+- Duplicate handling: Hybrid strategy. Keep section-local duplicates; dedupe only global/common content.
+- Product scope: Include both stages in feature intent, but implement DOM-to-JSON extraction first.
+- Sync model (future WYSIWYG): Bidirectional HTML ↔ JSON sync.
+- Image editing v1 (future WYSIWYG): Edit `img src` and `alt` only (exclude `srcset`/`picture` initially).
+- WYSIWYG editing scope v1 (future): Content updates only (text and image properties), no styling/layout editing.
+- Content identity: Hybrid identification. Reuse existing selectors/IDs where possible and add `data-*` IDs only where needed.
+
+## Resolved Questions
+- JSON shape should include subtopics rather than flat keys.
+- Metadata must be part of extraction.
+- Human editors will still work against the HTML site, so DOM-oriented extraction is preferred.
+- Full responsive image source editing is deferred to avoid layout breakage risk.
+
+## Open Questions
+- None currently.
+
+## Next Steps
+1. Proceed to planning (`/prompts:workflows-plan`) focused only on step 1: extraction pipeline and JSON structure contract.
+2. Follow with a second planning pass for step 2: WYSIWYG editing and robust bi-directional sync rules.

administration/docs/brainstorms/2026-03-04-wysiwyg-inline-editor-sync-brainstorm.md

@@ -0,0 +1,42 @@
+---
+date: 2026-03-04
+topic: wysiwyg-inline-editor-sync
+---
+
+# WYSIWYG Inline Editor + HTML/JSON Sync
+
+## What We're Building
+A local-first WYSIWYG editing mode for the static HTML snapshot where creators can edit page content directly on the rendered page. Text becomes editable on double-click using inline `contenteditable` behavior. Images open a small overlay for editing `src` and `alt` only.
+
+Edits must update both representations: the HTML content and the extracted content JSON. Persistence is local file write (not browser-only), so creators can save directly to project files during offline editing.
+
+This phase is content-only. It explicitly excludes CSS/layout editing.
+
+## Why This Approach
+Approach A (in-page edit mode + local save service) was selected because it matches the intended user behavior: fast direct edits where content lives visually. It minimizes training and friction for non-technical editors who already think in terms of “change this heading here.”
+
+YAGNI rationale: keep the first editor narrow and reliable. Only text and image content are editable, and image validation is warning-based (not blocking) to avoid blocking workflows while still reducing accidental visual breakage.
+
+## Key Decisions
+- Interaction model: Double-click inline editing for text.
+- Save behavior: Auto-save on blur/enter plus manual save/undo controls.
+- Image editing v1: Overlay for `src` + `alt` only.
+- Ratio validation: Warning (non-blocking), threshold set to 15% difference between current and replacement image aspect ratios.
+- Persistence model: Direct local file writes to `.html` and `.json` through a local helper service.
+- Sync model: Bidirectional HTML ↔ JSON.
+- Conflict default: HTML wins when both sides changed for the same mapped key.
+- Scope guard: No CSS/layout editing in this phase.
+
+## Resolved Questions
+- Inline editing is preferred over panel-based editing.
+- Save UX should support both auto-save and explicit controls.
+- Image editing should remain limited to `src`/`alt` in v1.
+- Ratio checks are advisory to preserve editor flow.
+- Local file write capability is required for practical offline usage.
+
+## Open Questions
+- None currently.
+
+## Next Steps
+1. Move to planning for step 2 (`/prompts:workflows-plan`) with focus on editor UX rules, content identity mapping, and local save contract.
+2. Keep implementation split into phases: text editing first, then image overlay and ratio warning behavior.