1 files changed, 233 insertions, 0 deletions
diff --git a/doc/index.rst b/doc/index.rst
new file mode 100644
index 0000000..f99cdbf
--- /dev/null
+++ b/doc/index.rst
@@ -0,0 +1,233 @@
+================================================================================
+Nixtamal Project Documentation
+================================================================================
+
+.. role:: ab
+.. role:: ac
+
+A Nix version pinning tool with first-class support for diverse version control
+systems and modern dependency management.
+
+------------------------------------------------------------------------------
+Overview
+------------------------------------------------------------------------------
+
+Nixtamal is an OCaml-based tool that addresses the limitations of Nix flakes
+while maintaining compatibility with traditional Nix workflows. It provides
+deterministic dependency pinning through lockfiles while supporting a diverse
+ecosystem of version control systems.
+
+**Key Capabilities:**
+
+• Multi-VCS support: Git, Darcs, Pijul, Fossil, and archives/files
+• KDL-based declarative configuration
+• Concurrent locking with domain-based parallelism
+• Schema versioning with upgrade paths
+• Template/Jinja2 support for dynamic URLs
+• Mirror support for resilience
+• Dual workflow: Traditional Nix + Flake compatibility
+
+**Website:** https://nixtamal.tech  
+**Community:** xmpp:nixtamal@chat.toastal.in.th?join
+
+------------------------------------------------------------------------------
+Quick Links
+------------------------------------------------------------------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   philosophy
+   manifest
+   roadmap
+   history
+
+------------------------------------------------------------------------------
+Current State (Phase 2)
+------------------------------------------------------------------------------
+
+**Version:** 0.2.0 (Schema Version)
+
+**Implemented Features:**
+
+✅ **Core Functionality**
+   - Manifest parsing and validation (KDL)
+   - Lockfile generation and management (JSON)
+   - Concurrent prefetching with Eio
+   - All major VCS types supported
+
+✅ **Schema Management**
+   - Versioned schemas (0.1.1 → 0.2.0)
+   - ``nixtamal upgrade`` command
+   - Automatic backup and rollback
+
+✅ **VCS Support**
+   - Git (with submodules, LFS)
+   - Darcs (with context/tag references)
+   - Pijul (channels, states, changes)
+   - Fossil (branches, tags, checkins)
+   - Nilla framework integration
+   - Files and archives
+
+✅ **Build System**
+   - Traditional Nix (default.nix, shell.nix)
+   - Flake support (flake.nix)
+   - Hybrid workflows
+
+✅ **Quality Assurance**
+   - Comprehensive test suite with coverage (36.87%)
+   - Property-based testing (QCheck)
+   - CI/CD integration
+
+**In Development:**
+
+🔄 **Phase 2.5** (Current Focus)
+   - Documentation website (nixtamal.tech)
+   - Test coverage expansion
+   - Visual dependency graphs
+
+------------------------------------------------------------------------------
+Installation
+------------------------------------------------------------------------------
+
+**Via Nix Flake:**
+
+.. code:: bash
+
+   nix run github:toastal/nixtamal -- --help
+
+**Via Traditional Nix:**
+
+.. code:: bash
+
+   nix-build release.nix
+   ./result/bin/nixtamal --help
+
+**Development Shell:**
+
+.. code:: bash
+
+   nix develop
+   dune build
+   dune runtest
+
+------------------------------------------------------------------------------
+Basic Usage
+------------------------------------------------------------------------------
+
+**Initialize a project:**
+
+.. code:: bash
+
+   nixtamal set-up
+
+**Lock dependencies:**
+
+.. code:: bash
+
+   nixtamal lock
+
+**Refresh to latest versions:**
+
+.. code:: bash
+
+   nixtamal refresh
+
+**Upgrade schema:**
+
+.. code:: bash
+
+   nixtamal upgrade --dry-run  # Preview changes
+   nixtamal upgrade            # Apply upgrade
+
+**Check for stale dependencies:**
+
+.. code:: bash
+
+   nixtamal list-stale
+
+------------------------------------------------------------------------------
+Architecture
+------------------------------------------------------------------------------
+
+**Core Modules:**
+
+``lib/input.ml``
+   Input type definitions for all supported VCS and file types
+
+``lib/manifest.ml``
+   KDL parsing and validation for manifest.kdl
+
+``lib/lockfile.ml``
+   Lockfile serialization and deserialization
+
+``lib/prefetch.ml``
+   VCS-specific prefetch implementations
+
+``lib/nixtamal.ml``
+   Core orchestration and workflow logic
+
+``lib/schema.ml``
+   Schema versioning and upgrade logic
+
+``lib/input_foreman.ml``
+   Concurrent input management and locking
+
+``bin/cmd.ml``
+   CLI command definitions and interface
+
+------------------------------------------------------------------------------
+Philosophy & Design Principles
+------------------------------------------------------------------------------
+
+See :doc:`philosophy` for detailed discussion of:
+
+• Why KDL over JSON/YAML
+• First-class VCS diversity
+• The anti-corporate stance
+• Privacy and decentralization
+• Dual workflow philosophy
+
+------------------------------------------------------------------------------
+Development Roadmap
+------------------------------------------------------------------------------
+
+See :doc:`roadmap` for complete phased development plan:
+
+• **Phase 1** ✅ Foundation (Completed)
+• **Phase 2** ✅ Core Features (Completed) 
+• **Phase 2.5** 🔄 Website & Documentation (Current)
+• **Phase 3** 📊 Visual Dependency Graphs (Next)
+• **Phase 4** 🔮 Future Enhancements
+
+------------------------------------------------------------------------------
+Development History
+------------------------------------------------------------------------------
+
+See :doc:`history` for complete project timeline:
+
+• Origins as a community fork
+• Transition from Darcs to Git
+• Flake integration development
+• Nilla framework support
+• Upstream porting effort (2026-04-14)
+
+------------------------------------------------------------------------------
+Contributing
+------------------------------------------------------------------------------
+
+**Code Style:**
+- Tabs for OCaml, spaces for Nix/dune (per .editorconfig)
+- OCamlFormat for formatting
+- SPDX headers required
+- Prefer Result over exceptions
+
+**Communication:**
+- Website: https://nixtamal.tech
+- XMPP MUC: xmpp:nixtamal@chat.toastal.in.th?join
+
+**License:**
+GPL-3.0-or-later (tools) / LGPL-2.1-or-later (libraries)
+
+------------------------------------------------------------------------------
+.. vim: set textwidth=80