Skip to content

README.md

Latest commit

 

History

History
293 lines (227 loc) · 17.2 KB

README.md

File metadata and controls

293 lines (227 loc) · 17.2 KB
Raw

Morphogen Documentation

Welcome to the Morphogen documentation! This guide will help you navigate the documentation based on what you want to accomplish.

💡 First time here? Start with the main README.md to understand Morphogen's vision and what makes it unique. Then come back here for detailed technical documentation.

🆕 New to Morphogen? Start Here

Choose your path:

🚀 Quick Start (15 minutes)

  1. Installation (5 min)
  2. Your first program (5 min)
  3. Run an example (5 min)

🎓 Learning Path (2-3 hours)

  1. Read Why Morphogen Exists (10 min)
  2. Try Complete Examples (30 min)
  3. Understand Core Concepts (30 min)
  4. Explore Domain Catalog - pick 2-3 domains (30 min)
  5. Read Architecture Overview (30 min)

🔬 Deep Dive (Advanced)

  1. Philosophy - Why Morphogen is designed this way
  2. Architecture - How it's implemented
  3. Specifications - Technical details
  4. ADRs - Design decisions

Not sure where to start? See Finding What You Need below

Quick Start

🚀 v1.0 Roadmap Active

Morphogen is on a focused path to v1.0!

📋 Read the Unified Roadmap ⭐

Current Status:

  • v0.12.0: Python-first runtime, examples, and documentation are the primary user surface
  • v1.0: packaging/install polish, coherent docs, and a tighter canonical example surface

Critical Path to v1.0:

  • 3D Visualization: PyVista integration, camera, lighting, scene graph (12 weeks)
  • Molecular Features: Geometry optimization, MD simulations
  • Community: docs, tutorials (git-based install, not PyPI)

See ROADMAP.md for complete details and implementation tracking.

Documentation Structure

🧠 Philosophy

Theoretical foundations and epistemological context (answers "WHY")

Note: Philosophy docs establish "why" Morphogen is designed this way. For "how" to implement it, see Architecture.

📐 Architecture

High-level design and architectural principles (answers "HOW")

Note: Architecture docs explain "how" to implement the principles from Philosophy.

📋 Specifications

Detailed technical specifications (21 documents)

📝 Architecture Decision Records (ADRs)

Why key architectural decisions were made (12 records)

📗 Usage Guides ⭐ NEW

Narrative how-to guides for specific domains — start here to use a domain

📖 Guides

How-to documentation for implementers

💡 Examples

Complete working examples demonstrating Morphogen capabilities

See also: examples/canonical/ — 3 canonical cross-domain examples that run end-to-end

🎯 Use Cases

Specific real-world applications

📚 Reference

Catalogs, operator references, and domain overviews (~420KB across 18 documents)

📖 Start here: Reference README ⭐ — Comprehensive index with navigation by task and experience level

Key sections:

  • Operator Catalogs (~154KB): Complete implementation-ready operator libraries
  • Visualization & Sonification (~115KB): Comprehensive visualization and sonification techniques
  • Theoretical Frameworks (~84KB): Mathematical foundations and pedagogical metaphors
  • Patterns & Best Practices (~72KB): Battle-tested architectural patterns
  • Domain Overviews (~40KB): High-level domain capabilities

Quick links:

🗺️ Roadmap & Planning

Primary: ROADMAP.md ⭐ — Unified development roadmap (v0.12.0 → v1.0)

Planning & Strategy:

📦 Archive History ⭐ NEW

Documentation of archived materials and their locations

What's archived:

  • Session artifacts from development sessions (point-in-time snapshots)
  • Historical planning documents (superseded by unified roadmap)
  • Analysis reports from v0.8.0 era (outdated technical analyses)
  • Mesh documentation (pre-consolidation)

Where: ~/Archive/morphogen/ - See ARCHIVE_HISTORY.md for complete details and inventory

Finding What You Need

I want to...

Recent Changes

2025-11-21: Major Documentation Reorganization & Language Roadmap

  • ✅ Documentation Organization - Consolidated and clarified documentation structure:
    • Moved analysis docs from root to docs/analysis/ (DOMAIN_VALIDATION_REPORT, MORPHOGEN_RENAME_ANALYSIS)
    • Moved type system spec to docs/specifications/level-3-type-system.md
    • Consolidated archives: moved archive/historical/ and archive/root-level-docs/ to docs/archive/
    • All documentation now properly organized in docs/ subdirectories
  • ✅ Language/Runtime Direction - See ROADMAP.md and STRATEGY.md:
    • Clear path to language 1.0 (target: 2026 Q2)
    • Production-ready vs planned features (physical units, cross-domain types, MLIR optimization)
    • Features under discussion (macros, effect system, ownership, pattern matching)
    • Decision framework for accepting new features
    • Community input process
  • ✅ Enhanced Navigation - Updated docs README with:
    • Links to newly organized documents
    • Language roadmap in prominent position
    • Cross-domain type system specification
  • ✅ Version Consistency - Updated STATUS.md header to clarify "Morphogen (Morphogen)"

2025-11-21: Documentation Improvements & Clarifications (earlier today)

  • ✅ Enhanced Reference Section - Created comprehensive Reference README with:
    • Navigation by task and experience level
    • Document relationships and cross-references
    • Statistics and breakdown by category (~420KB total)
  • ✅ Clarified Overlapping Docs - Added purpose sections to distinguish:
  • ✅ Improved Navigation - Added "WHY" vs "HOW" labels to Philosophy and Architecture sections

2025-11-21: New Theoretical Foundation Documents (~150KB)

2025-11-16: Major Documentation Reorganization

  • ✅ Created planning/ and analysis/ directories for better organization
  • ✅ Moved strategic planning docs from root to docs/planning/
  • ✅ Moved analysis documents from root to docs/analysis/
  • ✅ Moved orphaned docs to proper locations (specifications/, guides/)
  • ✅ Updated all version numbers to v0.10.0 (23 domains implemented)
  • ✅ Fixed inconsistencies across README, STATUS, and SPECIFICATION

2025-11-15: Initial Documentation Reorganization

  • ✅ Consistent lowercase naming throughout
  • ✅ Logical grouping by user intent (why/what/how/how-to)
  • ✅ Fixed ADR numbering (resolved duplicate 003 and 005 issues)
  • ✅ All specifications in one directory for easy discovery
  • ✅ Clear navigation paths for different user types
  • ✅ Moved patterns catalog out of ADRs to reference section

All file history has been preserved using git mv.

Documentation Best Practices

Using the Reveal Tool for Efficient Exploration

The reveal tool (scripts/reveal.sh) is designed for incremental documentation exploration, saving time and tokens:

# Start with structure (level 1) - see headings without full content
./scripts/reveal.sh 1 docs/architecture/domain-architecture.md

# Preview sample content (level 2) - representative sections
./scripts/reveal.sh 2 docs/specifications/chemistry.md

# Full content (level 3) - only when you need complete details
./scripts/reveal.sh 3 docs/guides/domain-implementation.md

Recommended workflow:

  1. Survey first: Use level 1 to see document structure
  2. Sample strategically: Use level 2 to preview interesting sections
  3. Read selectively: Only read full docs (level 3 or direct read) when needed

Token savings: Level 1 uses ~5-10% of tokens, level 2 uses ~20-30%, versus 100% for full reads.

See scripts/README.md for complete reveal tool documentation.

Cross-Referencing Conventions

  • Philosophy vs Architecture: Philosophy docs explain "WHY" (design principles), Architecture docs explain "HOW" (implementation approach)
  • ADRs reference specs: Check ADRs to understand design decisions, then read related specifications for implementation details
  • Examples reference specs: Working examples in examples/ demonstrate concepts from specifications/
  • Guides reference everything: Implementation guides in guides/ tie together philosophy, architecture, specs, and ADRs