coline/onset

1	# Using vcs (guide for coding agents)
2
3	This project uses vcs for version control, not git. A vcs workspace has no `.git` folder, so git commands don't work here. Use the commands below. If the user asks for a git command, do the vcs equivalent from the table at the end.
4
5	## How it works
6
7	- Your work is a change. A change has an ID made of letters (`rtnbkcvx`; the first 4 or more letters are enough). It saves itself: every vcs command saves first, and edits are saved within seconds. There's no staging and no commit.
8	- main is the shared line. It moves in numbered versions (main 48213). Numbers are always versions and letters are always changes.
9	- `vcs land` puts your change on main. The server merges it with whatever landed since you started, so don't pull, sync or rebase first.
10	- A workspace is a folder working on one change. Use one workspace per task, and never edit files in a folder another agent is using.
11
12	## The loop
13
14	1. `vcs status` shows where you are.
15	2. Edit files.
16	3. `vcs land -m "Title" -m "Why: … Checked: …"` lands the change. Afterwards you're on a new, empty change and your files are unchanged.
17
18	Every command ends with a `next:` line. When unsure, do what it says.
19
20	## When land doesn't go through
21
22	Read the exit code or `error.code`:
23
24	\| Exit \| Code \| Do this \|
25	\|---\|---\|---\|
26	\| 3 \| `conflict` \| Run `vcs sync`. Fix every file it lists by removing the `<<<<<<<` / `=======` / `>>>>>>>` markers and keeping the right code, then `vcs land` again. \|
27	\| 4 \| `checks_failed` \| Read the log link, fix the problem, then `vcs land` again. \|
28	\| 5 \| `waiting` \| A person has to land it. Tell the user and stop. Don't retry in a loop. \|
29	\| 8 \| `secret` \| Remove the secret from that line. Real secrets go in `.env`, which only the user can see. Never pass `--allow-secrets` unless the user tells you to. \|
30	\| 6 \| `offline` \| Your change is saved. Try `vcs land` again later. \|
31	\| 2 \| `no_description` \| Add `-m "Title"` and run it again. \|
32
33	## Working in parallel
34
35	- A separate task: `vcs get <project> <new-folder>`, then work only in that folder.
36	- Another task in the same folder: `vcs new "Title"`. The current change stays saved, and `vcs switch <id>` goes back to it.
37	- Building on a change that hasn't landed: `vcs new "Title" --on <id>`. Landing the new change lands both, in order.
38	- Picking up a change from another machine or agent: `vcs get <project> <folder> --change <id>`, or `vcs switch <id>` in a workspace you already have.
39
40	## Looking around
41
42	- `vcs diff` shows what your change changes (`--stat` for a summary).
43	- `vcs log` shows recent versions of main. `vcs log --changes` shows open changes and who has them.
44	- `vcs status <id>` shows any change, including whether it landed.
45
46	## Starting a project
47
48	- `vcs init <folder>` starts a new project that lives only on this machine. Landing works locally.
49	- `vcs publish upstream.codes/<owner>/<name>` puts a local project on the host, keeping its history.
50	- `vcs import <git-url> --to upstream.codes/<owner>/<name>` makes a project from a git or GitHub repository, with its full history.
51	- If a command says you're not signed in (exit 7), tell the user to run `vcs login`. Agents get a `VCS_TOKEN` from the user and never ask for passwords.
52
53	## Sharing and access
54
55	Only run these when the user asks.
56	- `vcs access <path> @group` makes a folder or file visible only to that group (and `@person` for one person, `me` for only the user).
57	- `vcs access <change> @person` lets someone see your change. Add `--edit` to let them work on it.
58	- `vcs access <path or change>` with no names shows who can see it.
59
60	## Fixing mistakes
61
62	- `vcs undo` undoes the last vcs command in this workspace. Run it again to go further back.
63	- It also undoes a land: main gets a new version that takes it back out, and the change reopens here.
64	- `vcs undo <version>` takes an older landed version back out of main without undoing anything else.
65	- `vcs restore <file>` puts a file back to how it was before your change.
66	- `--at "10 min ago"` brings back an earlier save of your own work.
67	- `--from <version>` takes the file from a version of main.
68	- `vcs drop` abandons the current change. `vcs undo` brings it back.
69
70	## Rules
71
72	- Descriptions: the first line says what changed. Then say why, and what you checked (tests, build).
73	- Don't land other people's changes, pass `--allow-secrets`, or change access unless the user asks.
74	- Don't print or copy what's in `.env` files. They belong to the user.
75	- Add `--json` when you want to parse output. It has the same facts, plus `next`.
76
77	## git → vcs
78
79	\| User asks for \| Run \|
80	\|---\|---\|
81	\| `git status`, `git diff`, `git log` \| `vcs status`, `vcs diff`, `vcs log` \|
82	\| `git add`, `git commit` \| Nothing: it's saved. Use `vcs describe "Title"` to set the description. \|
83	\| `git push`, "commit and push", "merge to main" \| `vcs land -m "Title"` \|
84	\| `git pull`, `git fetch`, `git rebase main` \| `vcs sync` \|
85	\| `git checkout -b`, a new branch \| `vcs new "Title"` \|
86	\| `git switch`, `git checkout <branch>` \| `vcs switch <change>` \|
87	\| `git stash` \| `vcs new` (the current change stays saved) \|
88	\| `git checkout -- <file>`, `git restore <file>` \| `vcs restore <file>` \|
89	\| `git reset`, `git reflog` to recover \| `vcs undo`, or `vcs restore <file> --at "<time>"` \|
90	\| `git revert` \| `vcs undo` right after landing, or `vcs undo <version>` for an older one \|
91	\| `git init` \| `vcs init <folder>` \|
92	\| `git clone` \| `vcs get <project> <folder>` \|
93	\| `git worktree add` \| `vcs get <project> <folder>` \|
94	\| open a pull request \| `vcs land` (if you can't land on your own, it asks the people who can) \|
95

colineonset

colineonset