Docs: no CONTRIBUTING.md, and nothing explains the client's browser-session design

[Waynting]

Two things a new contributor currently has to reverse-engineer, and I'd like
to write both up if you want them.

1. No CONTRIBUTING.md

The Contributing section in the README is one line, and the things that
actually trip someone up on a fresh clone are not in it:

• npm ci, not npm install — CI fails if the lockfile and package.json
  disagree, which is the point, but you only learn it from the workflow.
• The Node floor is exactly 20.18.1, not 20. The comment in ci.yml
  explains why; nothing a contributor reads first does.
• npm test globs test/*.test.ts, and test/e2e*.sh is deliberately
  outside it because it drives a live Overleaf account. ci.yml warns not
  to "fix" that by widening the glob — but only someone reading the workflow
  finds that warning. It belongs where a contributor looks before pushing.
• How to run the e2e suite at all: which env vars, what a throwaway project
  needs to contain.

#46 is the concrete case: npm run lint was a documented command that broke
on a fresh clone. That is the class of problem a contributor guide catches.

2. Nothing explains the shape of client.ts

docs/ covers the git remote helper and MCP — both user-facing. A
contributor opening client.ts cold has no way to know:

• There is no public Overleaf API; the client authenticates as a logged-in
  browser session and everything follows from that.
• Auth is a session cookie plus a CSRF token scraped out of the HTML.
  extractCsrfToken has three fallbacks because Overleaf changed its markup;
  listProjects has three for the same reason. Those look like defensive
  clutter until you know they are scar tissue.
• The file tree comes from a hand-rolled Socket.IO 0.9 client
  (getProjectFromSocket) because it left the meta tags. That is the most
  fragile surface in the repo and the least self-evident.
• uploadFile overwrites whole files. It is not the OT edit path the web
  editor uses — which is why push has no merge semantics, and why diff
  needed to exist at all.
• Which modules are pure and unit-testable without an account (diff.ts,
  ignore.ts, paths.ts, rename-plan.ts, scan.ts) and which need a live
  one. That split is deliberate and worth stating, since it tells a
  contributor where a new feature's logic should go.

I went through all of this from scratch recently, so I can write it while
it is still fresh — which also means I'm the right kind of wrong reader for
it, not someone who already knows the answers.

Questions before I draft anything

1. CONTRIBUTING.md at the root, or folded into the README? The root is
   currently lean and user docs live in docs/, so I'd rather follow your
   preference than guess.
2. The architecture note as docs/ARCHITECTURE.md, or kept as comments in
   client.ts? The file already carries substantial comments and I don't
   want to split one explanation across two places.
3. Anything about the release flow worth writing down — publish.yml is
   tag-triggered and the CHANGELOG is hand-maintained, neither of which is
   stated anywhere a contributor would look.

Happy to send it as one PR or two.

[aloth]

Yes to both, and your reasoning for why you are the right person to write them is the argument that convinces me.

1. CONTRIBUTING.md at the root. The README is 396 lines of user documentation and the Contributing section is one of them. What you describe - npm ci, the exact Node floor, why e2e*.sh sits outside npm test - is invisible to anyone who only uses olcli. GitHub also links a root CONTRIBUTING.md automatically when someone opens a PR or an issue, which is where it is needed. The existing one-liner stays and points at the file.

2. Both, split by distance. docs/ARCHITECTURE.md for what someone needs before opening a file: no public Overleaf API, the browser-session model, which modules are pure and testable without an account and which need a live one. Comments in client.ts for what is only understandable at the line - the three extractCsrfToken fallbacks are exactly that. Your scar tissue phrase is right, and scar tissue loses its meaning two files away. docs/ is where GIT-REMOTE.md and MCP.md already live.

3. Yes, in CONTRIBUTING.md rather than a separate file. publish.yml is tag-triggered and the CHANGELOG is hand-maintained; both affect anyone opening a PR, since it decides whether they write a CHANGELOG entry. That is a paragraph, not a document.

Two PRs, please. The contributor guide is process knowledge you have just lived through - quick to write, quick to review. The architecture note deserves more discussion, and in one PR the harder half would hold up the easy one.

Two repository behaviours worth capturing in the guide, both learned this week and neither discoverable from the outside:

CI on a first contribution sits at action_required until a maintainer approves it. GitHub holds workflows from first-time contributors. #47 sat that way for most of two days before anyone noticed, and from the contributor's side it looks like a broken PR rather than a queue. Nothing they can do about it, but knowing it is expected saves the wrong conclusion.

"Update branch" is now enabled on this repository. It merges main into the PR branch on a button press, so a stale branch no longer needs a maintainer pushing into someone's fork. Worth stating the limit though: the button only appears when the branch merges cleanly. Both PRs merged this week had real conflicts, so it would not have helped either of them, and resolving those still means a local merge.

Also worth knowing while writing this: the CI already checks out refs/pull/<n>/merge, so a PR is tested against the current main even when the branch itself is behind. Being out of date is not by itself a reason for a red build.