docs infrastructure

Dynamic Docs Index
& Publish Workflow

Replace the static hardcoded index with a manifest-driven page. Visual-explainer docs auto-publish from PR branches via GitHub Actions. Nested epic/feature hierarchy with spec and impl tag pills. Scroll-triggered animations throughout.

Three Pillars

JSON Manifest

docs-manifest.json on the docs branch. Nested structure: epics → features → docs. Decisions and roadmap as flat sections.

Dynamic Index

index.html fetches the manifest on load. Renders epic cards with nested feature sub-cards and SPEC/IMPL tag pills.

Auto-Publish

Two GitHub Actions workflows. Reusable publish-doc.yml engine + automated PR trigger. Manual dispatch as fallback.

Manifest Schema

docs-manifest.json

epics[]

number title desc color — each epic maps to a CSS variable (--lavender, --sky, --mint, --peach)

docs[]

title type href — type is spec or impl, href is relative path from docs root

features[]

number title desc — nested under parent epic, each has its own docs[] array

docs[]

Same structure as epic docs — title type href

decisions[]

tag title desc href — flat list, no nesting

roadmap[]

title desc href — accent-striped cards

Index Card Hierarchy

Go Orchestrator Core

Supervisor, agent state machine, DAG engine, gRPC, Redis

spec impl

CompareAndSetAgentState

Atomic state transitions with optimistic concurrency

spec

Pixel Office UI

coming soon

Tag pills are links. Each spec and impl pill is an <a> pointing to the visual-explainer HTML file. Features are nested inside their parent epic card with a left border in the epic's accent color.

Publish Workflow

Ctrl/Cmd + wheel to zoom. Scroll to pan. Drag when zoomed. Double-click to fit.

Dual checkout pattern. The workflow checks out the docs branch into ./docs-branch/ and the source ref into ./source/ using separate path: parameters. This avoids workspace conflicts. The manifest upsert uses actions/github-script to find-or-create the epic/feature entry and update the docs array by href match.

Developer Experience

Spec Phase

Finish writing the epic/feature spec
Run /visual-explainer on the spec
Run /animate for polish
Save as *-spec.html with meta tags
Commit, push — PR opens → auto-published

Implementation Phase

Implementation complete, PR reviewed
Run /visual-explainer on the impl
Run /animate for polish
Save as *-impl.html
Add ready-to-merge label → auto-published

Animation Catalog

Skeleton Shimmer

3 card-shaped placeholders with CSS gradient animation while the manifest loads. Crossfades to real content in 200ms.

background-size: 200% 100%; animation: shimmer 1.5s infinite;

Scroll Entrance

IntersectionObserver (threshold 0.1) fires fadeUp on each section and card group. Staggered by --i custom property.

opacity: 0 -> 1 translateY(12px) -> 0 delay: var(--i) * 0.1s

Card Hover

translateY(-3px), border highlight, box-shadow expansion, arrow slides right. All 200ms ease-out-quart.

transform: translateY(-3px); box-shadow: 0 8px 32px rgba(0,0,0,0.4); transition: 200ms var(--ease-out-quart);

Reduced Motion

All animation-duration and transition-duration collapse to 0.01ms. Content is immediately visible with no motion.

@media (prefers-reduced-motion: reduce) { animation-duration: 0.01ms !important; }

Migration: 12 Files + 1 Placeholder

File	Section	Type
visual-explainer/epic-1-go-orchestrator-core.html	epics[0]	spec
visual-explainer/epic-2-terminal-substrate.html	epics[1]	spec
visual-explainer/epic-3-model-gateway.html	epics[2]	spec
Epic 4 (no file)	epics[3]	placeholder
decisions/orchestration-pattern.html	decisions[0]	decision
decisions/ipc-communication.html	decisions[1]	decision
decisions/state-management.html	decisions[2]	decision
decisions/process-supervision.html	decisions[3]	decision
decisions/terminal-substrate.html	decisions[4]	decision
decisions/desktop-rendering.html	decisions[5]	decision
decisions/model-gateway.html	decisions[6]	decision
decisions/tui-alternative.html	decisions[7]	decision
visual-explainer/roadmap.html	roadmap[0]	roadmap

Legacy filenames preserved. The 3 existing epic explainers use filenames without the -spec suffix. They are not renamed. The automated discovery pattern (*-(spec|impl).html) intentionally does not match them — they are already seeded in the manifest.

Dynamic Docs Index& Publish Workflow

Dynamic Docs Index
& Publish Workflow