nearle admin agent

services/tools/help/onboarding-a-branch.md

@@ -0,0 +1,32 @@
+---
+question: What does creating a branch actually create?
+also:
+  - new outlet cannot sign in
+  - branch login has no password
+  - do I need a user before I add a branch
+  - onboarding a store what happens
+area: platform
+source: repositories/tenantRepository.go, src/auth/session.ts
+---
+A branch is never created on its own. It arrives with somebody who can run it,
+and there are two ways to give it one.
+
+Name an existing person and they are bound to the new outlet. They must already
+belong to that same merchant and must not be a till account — a userid from
+another business, or one that does not exist, is refused with the same message,
+and the branch is not created at all rather than left standing with nobody.
+
+Give an email instead and a login is spawned from it. That account is named
+after the shop, sits on the shop's email, and **is created with no password**.
+That is deliberate, not a fault: the first person to sign in is told the account
+needs a password and sets one, and only then can they get in.
+
+So a newly created branch whose operator reports they "cannot sign in" has
+usually not been broken — they have not been through the password step yet. The
+account is real and active; it simply has nothing to check a password against
+until somebody sets one.
+
+If the branch was created with neither an operator nor an email, it was not
+created. That combination is refused outright, because an outlet nobody can sign
+in to still appears in every list and every branch picker, and the first person
+to notice is whoever is standing in the shop.