diff --git a/SETUP.md b/SETUP.md new file mode 100644 index 0000000..fcd3c2f --- /dev/null +++ b/SETUP.md @@ -0,0 +1,163 @@ +# Setting up Granthi on a new computer + +Everything here is one command at a time. You need `git` and `python3` +(3.9 or newer). There is nothing to install — no package, no build. + +## Read this first: what you will see when you sign in + +Signing in does **not** hand you an account you already had somewhere else. +Granthi looks up your shre-id identity, and: + +* if it has seen you before, you get the same forge account as last time; +* if it has not, and the login it would use is free, it makes you a **new, + empty account**. + +So the first time you sign in on a new computer, `granthi-sync list` may show +**nothing**. That is not a failure. It means you are a new account and nobody +has given you access to anything yet. + +Granthi refuses to hand you an existing account just because the name lines +up. It will only join you to one if that account's email is the same as your +verified sign-in email. That rule is what stops somebody else claiming your +files, so it is worth the small surprise on day one. + +**Two ways to end up with your files, and it is worth choosing on purpose:** + +| | what happens | when to pick it | +|---|---|---| +| **Fresh account** (recommended) | You sign in, get a new empty account, and somebody shares the repos you need with you | Your everyday laptop. The token stored on the machine can only do what that account can do. | +| **Join an existing account** | An operator sets that account's email to your verified sign-in email first; then signing in joins you to it and you see everything it owns straight away | You want one identity everywhere and accept that the laptop then carries whatever that account can do | + +The fresh account is recommended for a plain reason: the token `link` saves on +the machine acts as that account. If you join an admin account, every computer +you sync from is carrying admin. + +## 1. Get the program + + git clone https://granthi.shre.ai/nirpa/granthi-sync.git + cd granthi-sync + +No account is needed for this step. + +## 2. Sign in + + ./bin/granthi-sync link + +It prints a web address and a short code. Open the address, type the code, and +approve — you have five minutes. When it finishes, your account exists and a +key is saved at `~/.granthi-sync/config.json`, readable only by you. You never +see or type a forge password. + +If the code runs out, **nothing was created** — no account, no key, no +half-finished state. Run `link` again. + +You do not need to be on any private network. The client talks to +`https://granthi-link.shre.ai`. + +## 3. See what you have + + ./bin/granthi-sync list + ./bin/granthi-sync list work- # only names containing "work-" + +This list comes from the forge, so it is exactly what you are allowed to see — +not a guess made on this computer. + +If it is empty, see the note at the top: you are a new account. Ask whoever +owns the repos to run `granthi-sync share --repo `, or to +add you to the right organisation. + +## 4. Bring folders down + + ./bin/granthi-sync get notes # by name + ./bin/granthi-sync get Nirlabinc/notes # when two teams both have a "notes" + ./bin/granthi-sync get --all --into ~/work # everything you are allowed to see + +If a plain name matches two repos, Granthi stops and shows you both rather +than guessing which one you meant. + +## 5. Or send a folder up + + ./bin/granthi-sync add ~/Documents/notes + +It becomes a private repo. Two things happen for your protection: + +* a starter `.gitignore` is written if the folder has none, covering `.env`, + `*.key`, `*.pem`, `id_rsa` and similar — those will **not** be synced; +* a folder holding more than 20,000 files or 512 MB is refused unless you add + `--force`, so you cannot upload your whole disk by accident. + +## 6. Keep it syncing + +Run it in a terminal: + + ./bin/granthi-sync watch + +Or leave it running in the background on a Mac: + + cp client/launchd/ai.granthi.sync.plist ~/Library/LaunchAgents/ + +Open that copied file and replace `/PATH/TO/granthi-sync` with the real path +to this folder. Then: + + launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.granthi.sync.plist + +Its log is `/tmp/granthi-sync.log`. + +### What syncing does to your folder + +It depends on what the folder was: + +* **A folder that was already a git project** — Granthi **never commits for + you**. Your history stays yours. Work you have not committed is copied to + the cloud with a timestamp so it is not only on this laptop. +* **A plain folder** — Granthi saves changes for you as it goes, and each save + is a point you can go back to. + +Either way, if your copy and the cloud copy have both moved on, Granthi +**stops and tells you**. It will never merge or overwrite your work to make +the conflict go away. + +## 7. Going back to an earlier version + + ./bin/granthi-sync snapshots ~/Documents/notes + ./bin/granthi-sync restore ~/Documents/notes --at 20260823T142530Z + +Restore writes to a **new folder**. It never overwrites what you have now — +if you are restoring, you have enough problems already. + +You can restore from a computer that never had the folder, including one +replacing a laptop that is gone. + +## 8. Sharing + + ./bin/granthi-sync share bob --repo notes # they have an account + ./bin/granthi-sync share bob --repo notes --revoke + ./bin/granthi-sync shared --repo notes # who can see it + ./bin/granthi-sync invite carol@example.com --repo notes # they do not yet + +An invite creates nothing until it is accepted. If the person never signs in, +nothing was ever made for them. + +## 9. Keeping track of your computers + + ./bin/granthi-sync devices # every computer signed in to your account + ./bin/granthi-sync logout # sign this computer out + ./bin/granthi-sync logout --device # sign out a lost one + ./bin/granthi-sync activity # sign-ins and sign-outs, with times + +Signing a computer out takes effect **at the server**, immediately. The key on +that machine stops working on its very next attempt — it is not a setting that +machine could ignore. That is what makes it useful for a laptop you have lost. + +Your folders are left alone when you sign out; only the key is removed. + +## If something looks wrong + +* **`list` is empty** — you are a new account, nobody has shared anything yet. +* **"Repository not found"** — you may not have access to that repo; run + `list` to see what you do have. +* **"this device's access has been revoked"** — someone signed this computer + out. Run `link` again. +* **A folder shows DIVERGED** — your copy and the cloud copy both changed. + Granthi is waiting for you on purpose. Nothing is lost; sort it out in git + or on the forge web page.