# Agent Instructions

## Project Snapshot

Sapling is a local-first, Git-native Markdown workspace built with Swift Package Manager. The package root is the source of truth; open `Package.swift` in Xcode when a GUI workflow is needed.

Primary targets:

- `SaplingApp`: SwiftUI app entry point and composition root.
- `SaplingCore`: shared domain models and business rules.
- `SaplingWorkspace`: workspace and file tree management.
- `SaplingGit`: Git protocols and provider implementations.
- `SaplingEditor`: hybrid Markdown editor MVVM surface.
- `SaplingRenderer`: Markdown rendering abstractions.
- `SaplingStorage`: configuration and metadata persistence.
- `SaplingLogging`: logging support.
- `SaplingUI`: shared SwiftUI components.

## Development Commands

Run commands from the repository root:

```sh
swift build
swift test
make validate
```

`make validate` runs formatting, linting, build, and tests. Use it before handing off substantial work when time permits.

Formatting and linting are available through:

```sh
make format
make lint
```

## Git Discipline

- Commit after every significant change unless the user explicitly asks not to commit.
- Keep commits focused on one coherent change.
- Check `git status --short` before editing and before committing.
- Do not include unrelated user changes in a commit.
- If the worktree already has changes you did not make, leave them in place and work around them.
- Never discard, reset, or overwrite user changes unless the user explicitly asks for that.
- Mention any uncommitted unrelated changes in the final handoff.

## Coding Guidelines

- Prefer the existing module boundaries and architecture described in `README` and `Docs/Architecture.md`.
- Keep changes narrowly scoped to the request.
- Use protocol-first seams already present in the codebase rather than adding global state or direct platform dependencies.
- Add or update tests when changing domain logic, editor behavior, Git behavior, or storage semantics.
- Keep Swift code formatted with the repository scripts.
- Avoid unrelated refactors while implementing a feature or fix.

## Handoff Expectations

Before finishing:

- Run the most relevant validation command you can afford for the change.
- Report exactly what was changed.
- Report which validation commands passed or why they were not run.
- If a significant change was made, ensure it is committed and include the commit hash in the handoff.