# Sapling 🌱

Sapling is a Git-native Markdown workspace for writing, research, documentation, and knowledge management.

Unlike traditional note-taking applications where version control is an afterthought, Sapling treats Git as a first-class concept. Projects are repositories, history is preserved through commits, attachments are tracked through Git LFS, and complex workspaces can be composed using Git submodules.

Sapling is designed to remain entirely client-side. Your files stay on your machine, your projects remain standard Git repositories, and synchronization is handled through any Git remote of your choice.

## Vision

Sapling aims to provide:

- A modern Markdown editing experience
- Native Git-based versioning
- Repository portability
- Long-term ownership of data
- No proprietary sync service
- No vendor lock-in

Your files are just files.

Your projects are just Git repositories.

## Core Concepts

### Workspace

A workspace is a local container for files, folders, and projects.

Workspaces are not versioned.

They may contain:

- Notes
- Scratch documents
- Local folders
- Sapling projects

### Project

A project is a Git repository.

Projects support:

- Local commits
- Branches
- Tags
- Remotes
- Push and pull
- Merge operations
- Git LFS
- Submodules

Projects can be opened and managed through the graphical interface or external Git tooling.

### Subprojects

Projects may contain subprojects through Git submodules.

Subprojects behave as independent repositories while remaining integrated into the parent project.

Typical use cases:

- Research repositories
- Shared assets
- Documentation libraries
- Reusable knowledge bases

## Features

### Markdown Editor

- Live hybrid Markdown editing
- Markdown source on the active line
- Rendered Markdown everywhere else
- Syntax highlighting
- Live preview

### Rendering

Initial support includes:

- Markdown
- LaTeX
- Mermaid diagrams
- Image embedding

Future support may include:

- Audio
- Video
- PDFs
- Advanced diagrams
- Interactive content

### Attachments

Attachments are stored within projects and tracked through Git LFS.

Examples:

- Images
- PSD files
- Design assets
- PDFs
- Binary resources

Non-Markdown files are opened using the operating system's default application.

### Git Integration

Git is a first-class citizen.

Supported operations include:

- Repository creation
- Clone
- Commit
- Push
- Pull
- Branch management
- Merge workflows
- History browsing
- Submodule management

Advanced users can open any project in a terminal and use Git directly.

## Platform Support

### macOS

Primary target platform.

Uses native macOS technologies and integrates with the system Git installation.

### iOS

Future target platform.

Will share as much code as possible with the macOS application while providing an embedded Git implementation suitable for iOS.

## Principles

- Local-first
- Git-native
- Markdown-first
- Open source
- Portable
- Extensible
- Client-side

## Status

Sapling is currently in active development.

## Project Layout

Sapling currently uses Swift Package Manager as the source-of-truth project layout. Open `Package.swift` in Xcode for app development or run SwiftPM commands from the repository root.

```text
Sapling/
├── Package.swift
├── Sources/
│   ├── SaplingApp/          # SwiftUI app entry point and composition root
│   ├── SaplingCore/         # Shared domain models and business rules
│   ├── SaplingWorkspace/    # Workspace and file tree management
│   ├── SaplingGit/          # Git protocols, macOS provider, embedded stub, mock provider
│   ├── SaplingEditor/       # Hybrid Markdown editor MVVM surface
│   ├── SaplingRenderer/     # Markdown rendering abstractions
│   ├── SaplingStorage/      # Configuration and metadata persistence
│   └── SaplingUI/           # Shared SwiftUI components
├── Tests/
│   └── SaplingCoreTests/
└── Docs/
    └── Architecture.md
```

## Development

Build:

```sh
swift build
```

Test:

```sh
swift test
```

Validate the Milestone 0 development workflow:

```sh
make validate
```

The validation target runs formatting, linting, build, and tests. If `swift-format` is installed, `make format` formats Swift sources in place; otherwise it falls back to the repository lint checks.

The app shell can open a local folder as a workspace, scan its filesystem hierarchy, visually distinguish Git repositories as projects, and open Markdown files through reusable document sessions. The architecture is intentionally protocol-first so the macOS implementation can use system Git while future iOS support can use an embedded Git implementation behind the same interfaces.

See [Docs/Architecture.md](Docs/Architecture.md) for module responsibilities, architectural decisions, and TODO markers.