Presentation layer redesign: four-view architecture (Diataxis)

[planeyang]

Overview

Redesign the Lions presentation layer around four distinct views, each serving one Diataxis documentation quadrant. The goal: replace GitHub as the reading experience for code.

The Problem

1. Landing page has no soul. Just "Browse annotated codebases" and a card grid. No hero, no story, no explanation of what Lions is. Needs a proper landing with a hero, a tribute to Lions' Commentary on UNIX, and references.
2. Summary is a wall of text. The Repo Landing page dumps a 2-3 paragraph blob. Needs tagline + structured abstract.
3. No visual architecture. Zero diagrams. DeepWiki has Mermaid diagrams on every overview page. We have text-only cluster cards.
4. Views are confused. The Code View sidebar mixes repo-level guide chapters, cross-cutting concepts, and file-level structure in one tabbed panel. Three zoom levels in one panel.
5. Concepts are buried. The concept index is a tab in the Code View sidebar instead of a first-class section on the Repo Landing page.
6. Entry points are invisible. Tiny gray badges at the bottom of the page, not clickable, no explanation of why. "Where do I start?" is the Lions architecture design documents #1 question and we barely answer it.
7. Annotation density is low. ~10% line coverage vs. 30-50% target.

Landing Page

Hero: "LIONS" in large display type. Tagline: "Read code like literature." GitHub URL input as primary CTA. See docs/plan/ux/08-landing-page.md.

Tribute to Lions' Commentary on UNIX (1977):

"These notes, which are intended to supplement the comments already present in the source code, are not essential for understanding the UNIX operating system. It is perfectly possible to proceed without them, and you should attempt to do so as long as you can."
— John Lions, 1977

3-4 paragraphs on who John Lions was, why it mattered, and how this project continues the tradition.

References: Lions' Commentary, Karpathy's MicroGPT blog, Knuth's Literate Programming, Bret Victor's Explorable Explanations, Diataxis framework, DeepWiki.

The Four Views (Diataxis)

	Learning	Working
Practical	Tutorial → Guide View (chapters, progressive)	How-to → Review View (PR diffs, agent API)
Theoretical	Explanation → Overview (tagline, diagrams, concepts)	Reference → Code View (annotated source)

View 1: Overview (Explanation)

• Tagline (1 sentence) + structured abstract (expandable, with subsection headers)
• Entry points above the fold — cards with reasons, clickable links
• Architecture diagram (Mermaid, type driven by repo taxonomy)
• Concept index (first-class section, not a tab)
• Reading guide chapter list

View 2: Guide (Tutorial)

• Own page, never embedded in Code View sidebar
• Sequential chapters, prose-first, inline code snippets with "View in Code" links

View 3: Code (Reference)

• File-scoped sidebar only: Structure + Concepts + References tabs
• Guide context reduced to a breadcrumb ("Ch. 3 → Guide View")
• Commentary toggle, prerequisites bar, cross-file footer

View 4: Review (How-to) — Future

• Annotated PR diffs with impact analysis
• Agent API: LLMs consume the annotation layer programmatically

Entry Points

New model with reasons:

class EntryPoint(BaseModel):
    file_path: str
    reason: str         # "Main server loop — follow a request end-to-end"
    line: int | None
    target: str          # "guide" | "code"

Repo Taxonomy

Repo Type	Diagram Style
Serving system	Data flow (request lifecycle)
ML model	Layer stack + math notation
Library	API surface → internals
Data structure	Node/memory layout
Compiler	Phase pipeline

Design Docs

See docs/plan/ux/ for the full plan (v2):

• README — Summary and key decisions
• Information Architecture — Diataxis mapping, views, entry points, DeepWiki comparison
• Navigation Patterns — Hub-and-spoke model, breadcrumbs
• View Designs — Four views with layout sketches
• Roadmap — Sprint breakdown + 6-month vision
• Design System — Colors, typography, spacing
• Open Questions — Trade-offs needing resolution
• Landing Page — Hero, Lions tribute, references
• User Personas — Four user profiles

Implementation Phases

Sprint 1: Landing Page + Clean Separation + Two-Layer Summary (1-2 weeks)

• Landing page redesign — Hero ("Read code like literature"), URL input, How It Works, Lions tribute blockquote, References section
• Add tagline, repo_type, and rich EntryPoint model to RepoSummary + Stage 4c prompt
• Two-layer summary on Repo Landing (tagline + expandable structured abstract)
• Entry point cards with reasons, above the fold, as clickable links
• Remove Guide tab from Code View sidebar, replace with breadcrumb
• Promote concept index to Repo Landing page
• Library cards use tagline instead of full summary

Sprint 2: Architecture Diagrams (2-3 weeks)

• Repo taxonomy classification in Stage 4c
• Architecture diagram generation (Mermaid, templated per repo type)
• Mermaid rendering component on Repo Landing
• Cross-file references in Code View footer

Sprint 3: Navigation + Polish (2 weeks)

• Breadcrumb trail across all views
• Commentary toggle in Code View
• Reading progress tracking (localStorage)
• Prerequisites bar in Code View

Future (months 3-6)

• Review View (annotated PR diffs)
• Agent API for programmatic access
• Dependency graph / concept map visualization
• Sandbox integration
• Range-based annotations + higher density
• Feedback loop and personalization