midsummer-sol 0.1.1

package/README.md

@@ -0,0 +1,99 @@
+# Sol
+
+**Sol is an agent-native version control system — a new `git`.** It keeps the
+shape you already know (`commit`, `branch`, `switch`, `merge`, `diff`,
+`clone`/`push`/`pull`) and adds what `git` structurally can't: every edit is
+captured automatically, history is content-addressed and tamper-evident, and an
+agent can author straight into version control with no working files at all.
+
+> The name: `sol` is the sun. Three letters, like `git`.
+
+## Install
+
+```sh
+npm i -g midsummer-sol      # exposes the `sol` command
+```
+
+Check it:
+
+```sh
+sol --version
+```
+
+## Authenticate
+
+Sign in once and Sol caches a token outside any repo so every machine command
+just works:
+
+```sh
+sol auth login              # opens a one-click link to finish sign-in in your browser
+sol auth status             # who you're signed in as
+sol auth logout
+```
+
+Prefer a token in your environment (CI, scripts)? Set `SOL_TOKEN` and Sol uses
+it directly — it always wins over the cached login:
+
+```sh
+export SOL_TOKEN=<your-token>
+```
+
+## Everyday commands
+
+```sh
+sol init                    # create ./.sol in the current directory
+# ...edit files...
+sol commit "first cut"      # snapshot the working tree + record a commit
+sol status                  # current branch + uncommitted changes
+sol log                     # commit history (sol log --all for every op)
+sol diff                    # working-tree changes (sol diff main feature between refs)
+sol watch                   # OR: auto-capture every change, hands-free
+```
+
+Branch and merge:
+
+```sh
+sol branch feature
+sol switch feature
+sol commit "work on feature"
+sol switch main
+sol merge feature           # 3-way merge; conflicts land in your working tree to resolve
+sol tag v1
+```
+
+Recover and inspect:
+
+```sh
+sol restore --from 3 app.py # a file (or the whole tree) from any ref
+sol show 5                  # a commit's message + its diff
+sol blame src/app.ts        # who/which commit last touched each line
+```
+
+A **ref** is a branch/tag name, a commit hash-prefix, an op sequence number, or
+`HEAD`. Set `SOL_ACTOR=you` to attribute your changes.
+
+## Remotes
+
+Sol is hosted. After `sol auth login`, clone and push to the hosted Sol with no
+extra setup — the default remote is `https://sol.midsummer.new`:
+
+```sh
+sol clone <owner>/<repo>    # clone into ./<repo>
+# ...work, commit...
+sol push                    # publish your commits
+sol pull                    # fast-forward sync
+```
+
+Point at a different host when you need to (a self-hosted or staging Sol). Either
+set `SOL_REMOTE`, or configure a remote per repo:
+
+```sh
+export SOL_REMOTE=https://sol.example.com     # override the default for all commands
+# or, per repo:
+sol remote https://sol.example.com my-repo
+sol push
+```
+
+## License
+
+MIT.