nearle admin agent

services/tools/help/assigning-a-partner.md

@@ -0,0 +1,31 @@
+---
+question: What does assigning a delivery partner to a merchant do?
+also:
+  - how does a shop get riders
+  - merchant has no riders to assign
+  - change which partner supplies a shop
+  - what does partnerid zero mean
+area: platform
+source: src/api/tenants.ts, src/api/deliveries.ts
+---
+A delivery partner is the company that supplies riders. Assigning one to a
+merchant makes that partner's riders available on the merchant's assign screen,
+alongside any riders the merchant hired itself.
+
+One partner routinely serves many merchants — this is not a one-to-one
+relationship, and reassigning a merchant does not take the partner away from
+anyone else.
+
+**Assigning no partner is a real setting, not an empty one.** A merchant with no
+partner uses its own riders, and that is a supported way to run a shop rather
+than a half-finished setup. A merchant with neither a partner nor its own riders
+has nobody to assign deliveries to, and that is what to check first when a shop
+reports an empty rider list.
+
+Only Nearle can set this. It is deliberately not something a merchant can edit
+about themselves, because a merchant who could set it would be able to move
+themselves under another partner's riders and billing.
+
+A partner works one district. If a merchant's branches sit in a district the
+partner does not cover, the partner's riders will not appear there even though
+the assignment exists.

services/tools/help/districts.md

@@ -0,0 +1,27 @@
+---
+question: What is a district, and what happens when a partner is onboarded in a new one?
+also:
+  - applocationid
+  - region not in the list
+  - riders not showing in a new city
+  - can I add a district
+area: platform
+source: repositories/partnerRepository.go
+---
+A district is the delivery region a partner works and a rider is placed in. It
+is not the same thing as a branch: a merchant has branches, a district covers
+whichever of them sit inside it.
+
+Onboarding a partner into a district that is not open yet **opens it**. The
+district is created along with the operating defaults every rider query needs,
+copied from a district already running rather than invented. So a partner can be
+set up in a city Nearle has not traded in before, without a separate step.
+
+This matters because a district that exists in name but has no operating
+configuration hides every rider placed in it. Riders can be created, they appear
+to save, and they are absent from every assign screen. The onboarding path
+creates both halves together so that state cannot be reached from the console.
+
+A partner works one district. If a partner's riders are not appearing for a
+merchant, check that the merchant's branches are in the same district as the
+partner, before looking at the riders themselves.

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.

services/tools/help/platform-vs-merchant.md

@@ -0,0 +1,26 @@
+---
+question: Why can I not see a shop's orders or stock from the platform workspace?
+also:
+  - buddy will not answer about a merchant
+  - nearle admin cannot see sales
+  - how do I check what is stuck for a tenant
+  - platform account no tenant
+area: platform
+source: services/tools/registry.go, services/agents/platform.yaml
+---
+A Nearle staff account reads across every merchant and belongs to none. It
+carries no shop, and every tool that reads orders, stock, tills or deliveries
+needs one — so from the platform workspace those questions have no answer rather
+than a slow one.
+
+That is the design, not a missing feature. "Every merchant at once" is not an
+answer to "what is stuck?", and a total across unrelated businesses would be a
+number nobody could act on.
+
+To look at one merchant's operations, work inside that merchant's own console,
+where the shop is fixed and the figures mean something.
+
+What can be answered from here is how Nearle itself works: what onboarding a
+branch creates, what assigning a delivery partner does, how the global catalogue
+reaches a shop's shelf, and why a till account is not a console login. If an
+answer would need a specific shop's data, it will say so rather than estimate.