Addition of roadmap.md and decisions.md

decisions.md

@@ -0,0 +1,352 @@
+# DECISIONS
+
+This document records major architectural and product decisions made during the development of Sapling.
+
+The goal is to preserve context and reasoning behind decisions so future contributors can understand why a particular approach was chosen.
+
+---
+
+# D-001 — Sapling Is Local-First
+
+Date: 2025-08
+
+Status: Accepted
+
+## Decision
+
+Sapling will be a local-first application.
+
+All user content lives on the local filesystem.
+
+No Sapling-managed cloud service will be required.
+
+## Rationale
+
+Users should own their data.
+
+Files must remain accessible outside of Sapling.
+
+The application should continue functioning without network connectivity.
+
+## Consequences
+
+Positive:
+
+- No vendor lock-in
+- Offline support
+- Simpler privacy story
+- Easier long-term maintenance
+
+Negative:
+
+- No built-in synchronization
+- Collaboration relies on Git workflows
+
+---
+
+# D-002 — Git Is Infrastructure, Not the Product
+
+Date: 2025-08
+
+Status: Accepted
+
+## Decision
+
+Git will be a first-class capability but not the primary user-facing concept.
+
+The editor and workspace experience take precedence over Git terminology.
+
+## Rationale
+
+Most users want versioning benefits without learning Git internals.
+
+Sapling should remain approachable to writers, researchers, and knowledge workers.
+
+## Consequences
+
+User interfaces should prefer language such as:
+
+- Snapshot
+- Changes
+- History
+
+over:
+
+- Commit
+- Staging
+- Reflog
+
+Advanced Git functionality will remain available.
+
+---
+
+# D-003 — Projects Are Git Repositories
+
+Date: 2025-08
+
+Status: Accepted
+
+## Decision
+
+Every Sapling project corresponds directly to a Git repository.
+
+No custom repository format will be introduced.
+
+## Rationale
+
+Git repositories are portable and understood by existing tooling.
+
+Users should be able to move between Sapling and other Git tools without migration.
+
+## Consequences
+
+Projects can be opened in:
+
+- Terminal
+- GitHub Desktop
+- SourceTree
+- VS Code
+- Any Git client
+
+without conversion.
+
+---
+
+# D-004 — Workspaces Are Not Versioned
+
+Date: 2025-08
+
+Status: Accepted
+
+## Decision
+
+Workspaces are organizational containers and are not Git repositories.
+
+Projects are versioned.
+
+Workspaces are not.
+
+## Rationale
+
+Users need a place for temporary notes, drafts, and experimentation.
+
+Not everything should require commits.
+
+## Consequences
+
+Workspace structure exists outside repository history.
+
+Projects remain independently portable.
+
+---
+
+# D-005 — Attachments Belong to Projects
+
+Date: 2025-08
+
+Status: Accepted
+
+## Decision
+
+Attachments are stored inside project directories.
+
+They are not stored in a database.
+
+They are not stored in a global asset store.
+
+## Rationale
+
+Repositories should remain self-contained.
+
+Cloning a repository should retrieve everything required to render its content.
+
+## Consequences
+
+Projects remain portable.
+
+Attachments participate naturally in version control.
+
+---
+
+# D-006 — Large Assets Use Git LFS
+
+Date: 2025-08
+
+Status: Accepted
+
+## Decision
+
+Large binary files should be managed through Git LFS.
+
+## Rationale
+
+Repositories containing images, PDFs, design assets, and media files can become excessively large.
+
+Git LFS is the industry-standard solution.
+
+## Consequences
+
+Sapling must detect and assist with LFS configuration.
+
+---
+
+# D-007 — Subprojects Use Git Submodules
+
+Date: 2025-08
+
+Status: Accepted
+
+## Decision
+
+Nested projects are implemented using Git submodules.
+
+## Rationale
+
+Submodules provide an existing, portable, Git-native solution.
+
+No custom dependency system is required.
+
+## Consequences
+
+Sapling must provide a significantly better UX around submodules than traditional Git tools.
+
+---
+
+# D-008 — Hybrid Markdown Editing Is a Core Feature
+
+Date: 2025-08
+
+Status: Accepted
+
+## Decision
+
+Sapling will implement hybrid Markdown editing.
+
+The active line displays source.
+
+Inactive lines display rendered content.
+
+## Rationale
+
+This editing model combines the readability of rendered Markdown with the precision of source editing.
+
+It is one of the primary differentiators of Sapling.
+
+## Consequences
+
+The editor becomes a critical architectural component.
+
+Prototype and validation work should occur early.
+
+---
+
+# D-009 — The Editor Is the Highest-Priority System
+
+Date: 2025-08
+
+Status: Accepted
+
+## Decision
+
+Editor quality takes precedence over Git features.
+
+## Rationale
+
+Users tolerate missing Git features.
+
+Users do not tolerate poor editing experiences.
+
+## Consequences
+
+Development milestones should prioritize:
+
+1. Editing
+2. Rendering
+3. Workspace management
+4. Git integration
+
+in that order.
+
+---
+
+# D-010 — Git Access Must Be Abstracted
+
+Date: 2025-08
+
+Status: Accepted
+
+## Decision
+
+All Git functionality must be accessed through a GitProvider abstraction.
+
+Application code should never invoke Git directly.
+
+## Rationale
+
+macOS and iOS have different implementation requirements.
+
+A clean abstraction improves portability and testability.
+
+## Initial Implementations
+
+MacGitProvider
+
+- Uses system Git
+
+EmbeddedGitProvider
+
+- Future iOS implementation
+
+## Consequences
+
+All repository operations must remain implementation-agnostic.
+
+---
+
+# D-011 — Markdown Files Remain Standard Markdown
+
+Date: 2025-08
+
+Status: Accepted
+
+## Decision
+
+Sapling documents are standard Markdown files.
+
+No proprietary format will be introduced.
+
+## Rationale
+
+Users should be free to edit documents with any editor.
+
+Knowledge should not be trapped inside Sapling.
+
+## Consequences
+
+Any Sapling-specific features should degrade gracefully in standard Markdown environments.
+
+---
+
+# D-012 — Platform Focus
+
+Date: 2025-08
+
+Status: Accepted
+
+## Decision
+
+macOS is the primary target platform.
+
+iOS support is a secondary objective.
+
+## Rationale
+
+The desktop writing experience is the primary use case.
+
+Starting with macOS reduces complexity and accelerates development.
+
+## Consequences
+
+Architecture should remain cross-platform where practical.
+
+Product decisions should optimize for desktop workflows first.

roadmap.md

@@ -0,0 +1,359 @@
+# ROADMAP
+
+# Sapling Roadmap
+
+This roadmap defines the major milestones required to transform Sapling from a prototype into a production-ready Git-native Markdown workspace.
+
+The roadmap focuses on delivering complete user workflows rather than isolated technical features.
+
+---
+
+# Vision
+
+Sapling is a local-first, open-source, Git-native Markdown workspace.
+
+Users should be able to:
+
+- Write documents
+- Organize knowledge
+- Manage projects
+- Version their work
+- Synchronize through Git
+- Own their data
+
+without relying on proprietary services.
+
+---
+
+# Milestone 0 — Foundation
+
+Status: In Progress
+
+Goal:
+
+Create a buildable application with a stable architecture and development workflow.
+
+Deliverables:
+
+- Project scaffolding
+- Shared macOS / iOS architecture
+- Core domain models
+- Dependency injection
+- Settings system
+- Logging infrastructure
+- Automated formatting and linting
+
+Success Criteria:
+
+- Application builds and launches
+- Core modules communicate correctly
+- Development workflow is stable
+
+---
+
+# Milestone 1 — Editor Prototype
+
+Status: Planned
+
+Goal:
+
+Validate Sapling's most important feature: the editing experience.
+
+Deliverables:
+
+- File tree sidebar
+- Document opening
+- Document saving
+- Markdown editor
+- Keyboard navigation
+- Undo / redo
+- Syntax highlighting
+
+Research:
+
+Investigate implementation options:
+
+- SwiftUI TextEditor
+- NSTextView
+- UITextView
+- Custom text engine
+
+Success Criteria:
+
+- Comfortable editing experience
+- Able to write and edit long documents
+- No major cursor or selection issues
+
+---
+
+# Milestone 2 — Hybrid Markdown Editing
+
+Status: Planned
+
+Goal:
+
+Implement Sapling's signature editing experience.
+
+Behavior:
+
+- Current line displays Markdown source
+- Non-active lines display rendered content
+- Editing feels seamless
+
+Supported Elements:
+
+- Headings
+- Emphasis
+- Links
+- Lists
+- Task lists
+- Code blocks
+
+Success Criteria:
+
+- Writing feels faster than traditional split-view editing
+- Rendering updates in real time
+- Cursor behavior remains intuitive
+
+---
+
+# Milestone 3 — Rendering Engine
+
+Status: Planned
+
+Goal:
+
+Provide high-quality Markdown rendering.
+
+Deliverables:
+
+- Full Markdown support
+- Syntax-highlighted code blocks
+- Tables
+- Callouts
+- Footnotes
+- Wikilinks
+
+Additional Support:
+
+- LaTeX
+- Mermaid diagrams
+- Image rendering
+
+Success Criteria:
+
+- Most Obsidian-style documents render correctly
+- Rendering performance remains smooth
+
+---
+
+# Milestone 4 — Workspace Management
+
+Status: Planned
+
+Goal:
+
+Introduce Sapling's organizational model.
+
+Deliverables:
+
+- Workspace creation
+- Folder management
+- File management
+- Project management
+- Drag and drop support
+
+Concepts:
+
+- Workspace
+- Project
+- Folder
+- Document
+- Attachment
+
+Success Criteria:
+
+- Users can organize real-world projects
+- Workspace structure feels natural
+
+---
+
+# Milestone 5 — Git Foundation
+
+Status: Planned
+
+Goal:
+
+Introduce Git as a first-class concept.
+
+Deliverables:
+
+- Repository initialization
+- Repository opening
+- Repository status
+- Commit creation
+- History viewing
+
+User Language:
+
+Prefer:
+
+- Snapshot
+- Changes
+- History
+
+Instead of exposing Git terminology everywhere.
+
+Success Criteria:
+
+- Users can version documents without using a terminal
+
+---
+
+# Milestone 6 — Attachments
+
+Status: Planned
+
+Goal:
+
+Support rich project assets.
+
+Deliverables:
+
+- Image attachments
+- Drag and drop import
+- Automatic link generation
+- Attachment browser
+
+Future Support:
+
+- PDFs
+- Audio
+- Video
+- Design assets
+
+Success Criteria:
+
+- Attachments integrate naturally into documents
+
+---
+
+# Milestone 7 — Git Collaboration
+
+Status: Planned
+
+Goal:
+
+Support synchronization and collaboration.
+
+Deliverables:
+
+- Remotes
+- Push
+- Pull
+- Fetch
+- Branch creation
+- Branch switching
+
+Success Criteria:
+
+- Projects can be synchronized across machines
+- Basic collaboration workflows are supported
+
+---
+
+# Milestone 8 — Git LFS
+
+Status: Planned
+
+Goal:
+
+Support large project assets.
+
+Deliverables:
+
+- Git LFS initialization
+- Automatic asset tracking
+- LFS status indicators
+
+Success Criteria:
+
+- Large attachments work reliably
+- Repository portability is maintained
+
+---
+
+# Milestone 9 — Subprojects
+
+Status: Planned
+
+Goal:
+
+Support modular project composition.
+
+Implementation:
+
+- Git submodules
+
+Deliverables:
+
+- Add subproject
+- Remove subproject
+- Update subproject
+- Browse subproject contents
+
+Success Criteria:
+
+- Nested repositories behave naturally
+- Complex knowledge structures are possible
+
+---
+
+# Milestone 10 — macOS Release Candidate
+
+Status: Planned
+
+Goal:
+
+Prepare Sapling for public use.
+
+Deliverables:
+
+- Performance optimization
+- Accessibility review
+- Documentation
+- Settings UI
+- Error handling
+- Migration support
+- Packaging and distribution
+
+Success Criteria:
+
+- Daily-driver quality
+- Stable for real projects
+
+---
+
+# Future Exploration
+
+Potential features after v1.0:
+
+- iOS application
+- Plugin system
+- Custom themes
+- Command palette
+- Workspace templates
+- Advanced graph views
+- Repository health checks
+- Knowledge publishing workflows
+- Alternative Git backends
+
+---
+
+# Guiding Principle
+
+The editor is the product.
+
+Git is infrastructure.
+
+Every milestone should improve the writing and knowledge-management experience first.