up/content-production-playbook.md

Content Production Playbook — Consciousness Garden

Purpose

Turn a topic list into organized, rich Zensical docs for the awakening/consciousness site. This document is the reusable task brief for any future content-writing run.

---

1. Inputs required

• Topic list (title + one-line intent per topic)
• Desired folder hierarchy preference:
  • docs/practices/ — guided practices
  • docs/teachings/ — longer essays, frameworks
  • docs/experiences/ — community stories, experiences
  • docs/reference/ — glossaries, diagrams, maps
  • docs/about/ — already exists; keep site meta here

---

2. Research workflow

For each topic:

1. Run a short Firecrawl/parallel-cli research pass to pull 2–4 high-quality references.
2. Favor primary sources, short readable articles, and non-copyright-restricted diagrams.
3. If the topic is technical or structural, prefer diagrammatic explanation.

---

3. Content standards

• Tone: calm, grounded, inviting — not performative spirituality.
• Length: 300–900 words per page unless the topic clearly demands more.
• Structure per post:
  • 1–3 sentence intro hook
  • 3–6 body sections with headings
  • 1 closing reflection or practice prompt
  • 1 related link into another page in the same hierarchy
• Accessibility: readable line length, alt text on images, reduced-motion safe animations.

---

4. Zensical features to use

• Admonitions: !!! note, !!! warning
• Collapsibles: ??? for optional depth
• Code/math only when genuinely clarifying a model or practice
• Mermaid diagrams: flowcharts, mindmaps, or journey maps when a concept benefits from visual structure
• markdown="1" for figures/hero-style images
• Keep internal links relative to docs/ paths

---

5. Images & media

• Prefer lightweight PNG/SVG or optimized JPEG.
• If video is added:
  • Use a poster image
  • Do not autoplay
  • Prefer HTML5 <video controls preload="none">
• For diagrams:
  • Mermaid first
  • If Mermaid is unsuitable, generate a simple SVG and embed it

---

6. Hierarchy rules

• Keep the tree shallow wherever possible: prefer docs/practices/grounding.md over deep nesting.
• Add an index.md to each section folder only if it adds navigational value.
• Avoid duplicate topics — search docs/ with ripgrep before creating a new page.

---

7. Linking policy

• Every new page should link to:
  • 1 nearby related page
  • 1 higher-level hub or index if available
• Use human-readable anchor text.
• Do not create orphan pages.

---

8. Review checklist

• Build succeeds with ./.venv/bin/zensical build
• Images render at reasonable size
• Internal links resolve in site/search.json
• Tone consistent with existing homepage
• No broken anchors in markdown
• Reduced-motion styles remain intact

---

9. Output convention

When producing posts from this playbook, return:

1. New file paths and folder tree
2. 1–3 sentence rationale for hierarchy choice per page
3. List of new internal links created
4. Any generated assets (docs/assets/images/*, docs/assets/diagrams/*)