1 files changed, 289 insertions, 0 deletions
diff --git a/doc/philosophy.rst b/doc/philosophy.rst
new file mode 100644
index 0000000..d364ca0
--- /dev/null
+++ b/doc/philosophy.rst
@@ -0,0 +1,289 @@
+================================================================================
+Nixtamal Philosophy & Design Principles
+================================================================================
+
+.. role:: ab
+.. role:: ac
+
+------------------------------------------------------------------------------
+Core Philosophy
+------------------------------------------------------------------------------
+
+Nixtamal exists because we believe:
+
+1. **Version pinning should be VCS-agnostic**
+2. **Configuration should be human-readable**
+3. **Users deserve privacy and control**
+4. **Software should be maintainable without megacorporate platforms**
+5. **The command line is still the best interface**
+
+------------------------------------------------------------------------------
+Why KDL?
+------------------------------------------------------------------------------
+
+We chose :ac:`KDL` (KDL Document Language) over JSON, YAML, or TOML for several
+reasons:
+
+**Readability**
+   KDL's node-based structure is immediately scannable. Unlike JSON's braces
+   and commas, or YAML's whitespace sensitivity, KDL looks like what it
+   represents:
+
+   .. code:: kdl
+
+      inputs {
+          nixpkgs {
+              git {
+                  repository "https://github.com/NixOS/nixpkgs"
+                  branch "nixos-unstable"
+              }
+          }
+      }
+
+**Semantic Richness**
+   Nodes can have properties, children, and values all in one structure. This
+   maps naturally to our domain model:
+
+   .. code:: kdl
+
+      hash algorithm=SHA256 expected="sha256-..."
+
+**No Whitespace Ambiguity**
+   Unlike YAML, KDL is unambiguous. No more "did I use tabs or spaces?"
+
+**Comment Preservation** (Future)
+   Once KDL v2 stabilizes, we can preserve comments through roundtrips,
+   enabling better tooling.
+
+------------------------------------------------------------------------------
+First-Class VCS Diversity
+------------------------------------------------------------------------------
+
+**The Git Monoculture Problem**
+
+The software industry has converged almost entirely on Git. While Git is
+capable, this monoculture:
+
+- Discourages innovation in version control
+- Creates single points of failure
+- Excludes projects using other VCS
+- Reinforces GitHub's dominance
+
+**Our Approach**
+
+Nixtamal treats all VCS equally:
+
+• **Git**: Full support with submodules, LFS, mirroring
+• **Darcs**: Patch-based, context-aware locking
+• **Pijul**: Channel and state-based references
+• **Fossil**: Checkin-based with built-in wiki/ticket integration
+• **Nilla**: Emerging framework support
+
+Each VCS gets:
+- Native prefetch integration
+- Appropriate reference types (branches, tags, contexts, states)
+- Proper lockfile serialization
+- Documentation and examples
+
+**Why This Matters**
+
+When you use Darcs or Pijul, you shouldn't have to convert to Git just to use
+Nix. Nixtamal meets you where you are.
+
+------------------------------------------------------------------------------
+The Anti-Corporate Stance
+------------------------------------------------------------------------------
+
+**Privacy and Surveillance**
+
+Nixtamal will never:
+- Use proprietary SaaS for core functionality
+- Phone home with usage data
+- Require accounts or authentication
+- Track users across projects
+
+**Platform Independence**
+
+The source code and community are hosted on:
+- Self-hosted Darcs repositories (original)
+- Community-maintained Git mirrors
+- XMPP for real-time communication
+- nixtamal.tech for project website
+
+We deliberately avoid:
+- GitHub (Microsoft surveillance)
+- Discord (proprietary, privacy-invasive)
+- Slack (corporate surveillance)
+- Twitter/X (disinformation platform)
+
+**Why This Is Practical**
+
+Modern distributed version control doesn't need a central platform. Darcs,
+Pijul, and Fossil all work perfectly well without GitHub. XMPP is a mature,
+federated protocol. The web existed before Cloudflare.
+
+------------------------------------------------------------------------------
+Dual Workflow Philosophy
+------------------------------------------------------------------------------
+
+**The Flake Controversy**
+
+Nix flakes are powerful but controversial:
+- Lockfiles in Git (bad for binary files)
+- JSON configuration (not human-friendly)
+- Centralized registry (single point of failure)
+- No standardized update workflow
+
+**Our Solution: Compatibility Without Compromise**
+
+Nixtamal supports both workflows:
+
+**Traditional Nix** (Default)
+   - ``manifest.kdl`` in repo
+   - ``lock.json`` in repo or separate
+   - Works with ``nix-build``, ``nix-shell``
+   - No evaluation caching issues
+
+**Flake Integration** (Optional)
+   - Use ``nixtamal.lib.fromNixtamalProject`` in flake.nix
+   - Consume nixtamal projects as flake inputs
+   - Generate flake.lock from nixtamal lockfile
+   - Best of both worlds
+
+**Why Both?**
+
+Users should choose their workflow. Some teams love flakes. Others need
+traditional Nix. Nixtamal doesn't force a choice.
+
+------------------------------------------------------------------------------
+Privacy by Design
+------------------------------------------------------------------------------
+
+**What We Don't Collect**
+
+- No analytics
+- No crash reporting
+- No usage statistics
+- No dependency telemetry
+
+**What Stays Local**
+
+- Lockfile generation
+- Prefetch operations
+- Mirror selection
+- Template rendering
+
+**Network Activity**
+
+The only network activity is:
+1. Prefetching inputs (to your own stores)
+2. Checking for latest versions (when you run ``refresh``)
+3. Fetching nixpkgs (if you use the default)
+
+That's it. No metrics. No tracking. No bullshit.
+
+------------------------------------------------------------------------------
+Command Line as Primary Interface
+------------------------------------------------------------------------------
+
+**The TUI Question**
+
+We've considered adding a Text User Interface (TUI). While appealing, we're
+hesitant because:
+
+- CLI is scriptable; TUI is not
+- CLI works over SSH; TUI requires terminal support
+- CLI is timeless; TUIs become dated
+- CLI is accessible; TUIs may not be
+
+**Our Compromise**
+
+- CLI is primary and always will be
+- TUI may be added as optional enhancement (Phase 4)
+- All functionality available via CLI first
+- Web interface for visualization (Phase 3)
+
+------------------------------------------------------------------------------
+Sustainability and Maintenance
+------------------------------------------------------------------------------
+
+**Long-term Viability**
+
+Nixtamal is designed to be maintainable:
+
+- OCaml is a stable, typed language with decades of history
+- KDL is a simple, well-specified format
+- No external service dependencies
+- Clear module boundaries
+- Comprehensive tests
+
+**Community Governance**
+
+The project follows a "benevolent dictator" model:
+- toastal maintains and decides direction
+- Community contributions welcome
+- Forks encouraged if direction diverges
+- No CLA or corporate ownership
+
+**Funding**
+
+Currently unfunded. If you want to support:
+- Contribute code
+- Write documentation
+- Package for distributions
+- Donate to toastal
+
+------------------------------------------------------------------------------
+Comparison with Alternatives
+------------------------------------------------------------------------------
+
+**vs. Flakes**
+
++ Better VCS support
++ Human-readable config (KDL vs JSON)
++ External lockfiles
++ No evaluation caching issues
+- Less integrated with nix command
+- Smaller ecosystem
+
+**vs. npins**
+
++ First-class VCS diversity
++ KDL > JSON
++ Template support
++ Schema versioning
+- More complex
+- OCaml dependency
+
+**vs. niv**
+
++ Modern codebase
++ Better error handling
++ Schema upgrades
+- No niv import (yet)
+- Less mature ecosystem
+
+**vs. Built-in fetchers**
+
++ Unified interface
++ Lockfile management
++ Stale checking
++ Update workflow
+- Additional dependency
+
+------------------------------------------------------------------------------
+Conclusion
+------------------------------------------------------------------------------
+
+Nixtamal represents a bet: that users want:
+
+1. **Control** over their tooling
+2. **Privacy** by default
+3. **Diversity** in VCS support
+4. **Compatibility** without lock-in
+5. **Sustainability** over hype
+
+If these values resonate with you, welcome. If not, there are plenty of
+alternatives. Choice is the point.
+
+.. vim: set textwidth=80