@thatopen/services 0.6.0 → 0.8.0

package/docs/cli/publish.md

@@ -1,31 +1,31 @@
----
-description: "Build and upload the project to the platform. Automatically detects app vs cloud component from the local .thatopen config. On first publish, saves the assigned item ID back to .thatopen so subsequent runs update the same item instead of creating a new one."
----
-
-## thatopen publish
-
-Builds the project and uploads it to the platform. Works for both apps and cloud components — the project type is read from `.thatopen` (`itemType: APP | COMPONENT`).
-
-First publish creates the item and auto-saves its ID to `.thatopen`. Subsequent publishes update that same item.
-
-**Usage:**
-```bash
-thatopen publish [flags]
-```
-
-**Flags:**
-
-- `--name <name>` — Item name on the platform. Defaults to `name` in `package.json`.
-- `--version-tag <tag>` — Version tag. Defaults to `version` in `package.json`.
-- `--app-id <id>` — Target an existing app by ID (overrides `.thatopen`).
-- `--component-id <id>` — Target an existing cloud component by ID (overrides `.thatopen`).
-- `--skip-build` — Skip the build step and upload the existing `dist/bundle.js`.
-- `--icon <path>` — Path to an icon file (PNG, WebP, or ICO, max 512 KB). Saved to `.thatopen` for future publishes.
-
-**Examples:**
-```bash
-thatopen publish
-thatopen publish --version-tag 2.0.0
-thatopen publish --skip-build
-thatopen publish --icon assets/icon.png
-```
+---
+description: "Build and upload the project to the platform. Automatically detects app vs cloud component from the local .thatopen config. On first publish, saves the assigned item ID back to .thatopen so subsequent runs update the same item instead of creating a new one."
+---
+
+## thatopen publish
+
+Builds the project and uploads it to the platform. Works for both apps and cloud components — the project type is read from `.thatopen` (`itemType: APP | COMPONENT`).
+
+First publish creates the item and auto-saves its ID to `.thatopen`. Subsequent publishes update that same item.
+
+**Usage:**
+```bash
+thatopen publish [flags]
+```
+
+**Flags:**
+
+- `--name <name>` — Item name on the platform. Defaults to `name` in `package.json`.
+- `--version-tag <tag>` — Version tag. Defaults to `version` in `package.json`.
+- `--app-id <id>` — Target an existing app by ID (overrides `.thatopen`).
+- `--component-id <id>` — Target an existing cloud component by ID (overrides `.thatopen`).
+- `--skip-build` — Skip the build step and upload the existing `dist/bundle.js`.
+- `--icon <path>` — Path to an icon file (PNG, WebP, or ICO, max 512 KB). Saved to `.thatopen` for future publishes.
+
+**Examples:**
+```bash
+thatopen publish
+thatopen publish --version-tag 2.0.0
+thatopen publish --skip-build
+thatopen publish --icon assets/icon.png
+```

package/docs/cli/run.md

@@ -1,26 +1,26 @@
----
-description: "Build and run a cloud component locally as a child process, mirroring the backend execution environment. Accepts execution parameters as JSON via --params, validates them against declarations.json, and streams progress output to the terminal."
----
-
-## thatopen run
-
-Builds and executes a cloud component locally, replicating what the platform's cloud engine does. Useful for testing component logic and parameters before publishing.
-
-Execution output (`MESSAGE`, `PROGRESS`, `SUCCESS`, `FAIL`) is streamed to the terminal with elapsed time.
-
-**Usage:**
-```bash
-thatopen run [flags]
-```
-
-**Flags:**
-
-- `--params <json>` — Execution parameters as a JSON string. Default: `'{}'`. Validated against `declarations.json` if present (warns, does not fail).
-- `--skip-build` — Skip the build step and run the existing `dist/bundle.js`.
-
-**Examples:**
-```bash
-thatopen run
-thatopen run --params '{"fileId": "abc123"}'
-thatopen run --skip-build
-```
+---
+description: "Build and run a cloud component locally as a child process, mirroring the backend execution environment. Accepts execution parameters as JSON via --params, validates them against declarations.json, and streams progress output to the terminal."
+---
+
+## thatopen run
+
+Builds and executes a cloud component locally, replicating what the platform's cloud engine does. Useful for testing component logic and parameters before publishing.
+
+Execution output (`MESSAGE`, `PROGRESS`, `SUCCESS`, `FAIL`) is streamed to the terminal with elapsed time.
+
+**Usage:**
+```bash
+thatopen run [flags]
+```
+
+**Flags:**
+
+- `--params <json>` — Execution parameters as a JSON string. Default: `'{}'`. Validated against `declarations.json` if present (warns, does not fail).
+- `--skip-build` — Skip the build step and run the existing `dist/bundle.js`.
+
+**Examples:**
+```bash
+thatopen run
+thatopen run --params '{"fileId": "abc123"}'
+thatopen run --skip-build
+```

package/docs/cli/serve.md

@@ -1,43 +1,43 @@
----
-description: "Start a local dev server for a browser app. Uses esbuild in watch mode and serves the IIFE bundle on port 4000 with SSE live reload. To connect: open the project on platform.thatopen.com, click the Local App icon, then Get Started."
----
-
-## thatopen serve
-
-Builds the app in watch mode and serves the IIFE bundle locally. On every save, esbuild rebuilds and the platform reloads the bundle automatically via SSE.
-
-Does **not** open a browser tab — the app runs inside the platform iframe. Open your project on the platform, then click the debug button to connect it to the local server.
-
-**Usage:**
-```bash
-thatopen serve [flags]
-```
-
-**Flags:**
-
-- `--port <port>` — Port to serve the bundle on. Default: `4000`.
-
-**Endpoints served:**
-
-- `GET /bundle.js` — The compiled IIFE bundle.
-- `GET /bundle.js.map` — Source map.
-- `GET /events` — SSE stream for live reload.
-
-**Example:**
-```bash
-thatopen serve
-thatopen serve --port 4321
-```
-
-**Connecting the platform to your local server:**
-
-1. Go to [https://platform.thatopen.com](https://platform.thatopen.com) and open a project (create one first if needed).
-2. In the top right corner, click the **Local App** icon.
-3. Click **Get Started**.
-
-The platform loads the bundle from port 4000 and renders the app inside the project context, with full access to its models, data, and users. The dev server must be running before opening this URL — if nothing is served on port 4000, the platform will fail to load the app.
-
-The resulting URL follows this pattern:
-```
-https://platform.thatopen.com/dashboard/projects/{projectId}/apps/local-app
-```
+---
+description: "Start a local dev server for a browser app. Uses esbuild in watch mode and serves the IIFE bundle on port 4000 with SSE live reload. To connect: open the project on platform.thatopen.com, click the Local App icon, then Get Started."
+---
+
+## thatopen serve
+
+Builds the app in watch mode and serves the IIFE bundle locally. On every save, esbuild rebuilds and the platform reloads the bundle automatically via SSE.
+
+Does **not** open a browser tab — the app runs inside the platform iframe. Open your project on the platform, then click the debug button to connect it to the local server.
+
+**Usage:**
+```bash
+thatopen serve [flags]
+```
+
+**Flags:**
+
+- `--port <port>` — Port to serve the bundle on. Default: `4000`.
+
+**Endpoints served:**
+
+- `GET /bundle.js` — The compiled IIFE bundle.
+- `GET /bundle.js.map` — Source map.
+- `GET /events` — SSE stream for live reload.
+
+**Example:**
+```bash
+thatopen serve
+thatopen serve --port 4321
+```
+
+**Connecting the platform to your local server:**
+
+1. Go to [https://platform.thatopen.com](https://platform.thatopen.com) and open a project (create one first if needed).
+2. In the top right corner, click the **Local App** icon.
+3. Click **Get Started**.
+
+The platform loads the bundle from port 4000 and renders the app inside the project context, with full access to its models, data, and users. The dev server must be running before opening this URL — if nothing is served on port 4000, the platform will fail to load the app.
+
+The resulting URL follows this pattern:
+```
+https://platform.thatopen.com/dashboard/projects/{projectId}/apps/local-app
+```

package/docs/cli/swap.md

@@ -1,30 +1,30 @@
----
-description: "Toggle or explicitly set the engine library mode between stable public packages (@thatopen/*) and private beta packages (@thatopen-platform/*-beta). Updates package.json and .thatopen, then runs npm install. Source code never changes — aliases handle resolution."
----
-
-## thatopen swap
-
-Switches the project between stable and beta engine libraries. Without flags, it toggles from the current state. Updates `package.json` dependencies and sets `beta` in `.thatopen` so `thatopen serve`, `thatopen local-server`, and `vite build` all pick up the change automatically.
-
-Source code stays unchanged — `@thatopen/components` imports resolve to the correct package via esbuild/vite aliases based on the `beta` flag in `.thatopen`.
-
-**Usage:**
-```bash
-thatopen swap           # toggle: stable → beta or beta → stable
-thatopen swap --beta    # force beta
-thatopen swap --stable  # force stable
-```
-
-**Flags:**
-
-- `--beta` — Switch to beta libraries (`@thatopen-platform/*-beta`).
-- `--stable` — Switch back to stable public libraries (`@thatopen/*`).
-
-**Examples:**
-```bash
-thatopen swap
-thatopen swap --beta
-thatopen swap --stable
-```
-
-> Beta packages are private and the access must be explicitly granted by That Open Company.
+---
+description: "Toggle or explicitly set the engine library mode between stable public packages (@thatopen/*) and private beta packages (@thatopen-platform/*-beta). Updates package.json and .thatopen, then runs npm install. Source code never changes — aliases handle resolution."
+---
+
+## thatopen swap
+
+Switches the project between stable and beta engine libraries. Without flags, it toggles from the current state. Updates `package.json` dependencies and sets `beta` in `.thatopen` so `thatopen serve`, `thatopen local-server`, and `vite build` all pick up the change automatically.
+
+Source code stays unchanged — `@thatopen/components` imports resolve to the correct package via esbuild/vite aliases based on the `beta` flag in `.thatopen`.
+
+**Usage:**
+```bash
+thatopen swap           # toggle: stable → beta or beta → stable
+thatopen swap --beta    # force beta
+thatopen swap --stable  # force stable
+```
+
+**Flags:**
+
+- `--beta` — Switch to beta libraries (`@thatopen-platform/*-beta`).
+- `--stable` — Switch back to stable public libraries (`@thatopen/*`).
+
+**Examples:**
+```bash
+thatopen swap
+thatopen swap --beta
+thatopen swap --stable
+```
+
+> Beta packages are private and the access must be explicitly granted by That Open Company.

package/docs/flow-architecture.md

@@ -386,4 +386,4 @@ Rhino kernel, so a converter can run server-side while real modelling operations
 
 The concrete wire formats — where each file lives on the platform, what the proposal envelope
 contains, how the queue and the ownership registry work — are in
-[the plugin guide](./flow-plugin-guide.md), which is what to read if you are writing a plugin.
+[the plugin guide](https://raw.githubusercontent.com/ThatOpen/platform_services/main/docs/flow-plugin-guide.md), which is what to read if you are writing a plugin.

package/docs/flow-plugin-guide.md

@@ -1,6 +1,6 @@
 # Writing a flow plugin
 
-The concrete contract. [The architecture notes](./flow-architecture.md) say why any of this is
+The concrete contract. [The architecture notes](https://raw.githubusercontent.com/ThatOpen/platform_services/main/docs/flow-architecture.md) say why any of this is
 shaped the way it is; this says what the bytes look like.
 
 Nothing here is aspirational. Every rule below is what the Revit and Rhino plugins already do, and
@@ -152,6 +152,32 @@ made every proposal declare its units, which looked careful and was a bug waitin
 an author state a unit while writing coordinates in an axis convention the target does not use, a
 mistake no declared unit can catch.
 
+### Who wrote it
+
+`author` is free text for a timeline to print. `userId` is the one that has to be right: it is what
+the platform's own member component resolves into a real name and face. Get it wrong and the
+proposal shows up under somebody else's avatar, which is worse than showing none.
+
+**In a browser app, take it from `getProjectData`.** It answers with `currentUser` already resolved
+server-side, and the members it lists are keyed by exactly the id the history panel indexes:
+
+```ts
+const { currentUser } = await client.getProjectData(projectId);
+const userId = currentUser?.user._id;      // what the avatar resolves against
+const author = currentUser?.user.fullName; // what the timeline prints
+```
+
+**Do not look for it on the client's context.** `client.context` is the four fields the platform
+injects into the iframe: `appId`, `projectId`, `accessToken`, `apiUrl`. Reading `context.userId` or
+`context.user.name` yields `undefined`, and both failures are silent: the envelope simply ships
+without a `userId`, and the panel falls back to passing `author` as the email, so the member
+component renders whatever it makes of a string that names nobody. A converter did exactly this, and
+it looked fine until somebody noticed the proposal was wearing another person's face.
+
+**In a native plug-in there is no such call**, so read the `u` claim out of the API key's JWT payload
+(base64url, no signature check, since this only decides which name to display). That is what the
+Revit add-in does.
+
 ### The verbs
 
 One per item, in the attribute `flow:op`:

package/docs/platform-token.md

@@ -0,0 +1,81 @@
+# Logging in to That Open Platform
+
+Everything else in these guides needs this, and it is the same three lines every time, so it lives
+here rather than in each of them.
+
+## Get the token
+
+Say this to the user, and wait:
+
+> "To log in I need a That Open Platform **access token**. You create it yourself:
+> **https://platform.thatopen.com/dashboard/data → API Tokens → create → copy**, then paste it
+> here."
+
+**Never print it back, never write it into a file, never commit it.** Not into a script, not into a
+`.env` you are about to show, not into a chat message quoting the command you ran.
+
+## Log in
+
+```bash
+thatopen login --token <TOKEN>
+```
+
+Credentials go to `~/.thatopen/config.json`, as `accessToken` and `apiUrl`. `--local` writes them to
+a `.thatopen` file in the project instead, which is what a scaffolded project uses.
+
+You do not need an npm account or an npm token for the private packages. The CLI derives access to
+them from this one.
+
+## Everyone is on production
+
+**Do not ask the user which environment they want.** Production is the answer, it is the default,
+and the plain command above is already correct. Asking turns a decision nobody has into a question
+they cannot answer, at the worst possible moment — the first thing you say to them.
+
+There is a `dev` platform, and it exists for the people building That Open Platform itself. If the
+user is one of them they already know, and they will tell you without being asked.
+
+Everything below this line is for that case only. If nothing has mentioned dev, skip it.
+
+<details>
+<summary>Dev, for the platform team</summary>
+
+Two platforms, not two views of one. Separate accounts, separate tokens, separate projects. A token
+from one is refused by the other, and a model published to the wrong one lands somewhere the user's
+team cannot see — while every command reports success.
+
+```bash
+thatopen login --token <TOKEN> --api-url https://dev.platform.thatopen.com
+```
+
+Its dashboard is the same page on that host: `https://dev.platform.thatopen.com/dashboard/data`.
+
+</details>
+
+## Check, do not ask
+
+**`login` prints "Logged in successfully" and does not name the environment**, so nothing on screen
+would contradict a wrong assumption. Read `apiUrl` from `~/.thatopen/config.json` yourself.
+
+If it says production — which it will — say nothing about it and carry on. There is no decision to
+report.
+
+**Only if it says dev**, and the user has not told you they work there, is there anything to say:
+
+> "This machine is pointed at the dev platform, which is the one the That Open team builds on. I'll
+> move it to production — that will need a token from **https://platform.thatopen.com/dashboard/data**,
+> since dev tokens are not accepted there."
+
+Check this **even when the machine is already logged in**, and especially then. A saved login is
+whoever used this machine last, not an answer to a question you have asked.
+
+## When it fails
+
+- **`Unauthorized`** — the token is invalid, expired, or from the other environment. Production
+  tokens use no `--api-url`; dev tokens need it. Ask for a fresh one from the same environment as
+  the URL you are using.
+- **HTTP 403 on `item/folder?projectId=…`** — login worked. The account simply has no access to that
+  project, or the project is in the other environment. Confirm the project id with the user before
+  assuming anything is broken.
+- **A private package fails to install** — you are not logged in, or logged in to the environment
+  that does not have it. Log in again and retry; there is no separate npm login to do.

package/docs/revit-collab-quickstart.md

@@ -37,11 +37,21 @@ the point.
   run, briefly, before you run it.
 - After each command, **check the output** before moving on. A command that answered is not the
   same as a command that did what you wanted.
+- **Whatever you find already set up on this machine is somebody's previous session, not this
+  user's choice.** A saved login, an environment, a joined project, a model already open in Revit:
+  none of it is an answer to a question you have not asked. Report what you found and ask. This is
+  the single most likely way to get the whole thing wrong while every command succeeds.
 
 ---
 
 ## Step 0 — Ask what the user wants to do
 
+**Only if they have not already told you.** "I want to start a new collaborative project in Revit
+and here is my file" is (A), said plainly. Reading it back as a four-way menu costs the user a
+whole turn to answer something they just said, and that is the single most common way this guide
+wastes somebody's time. Work out which one it is, say which one you took it to be in one line, and
+carry on. Ask only for what is genuinely missing.
+
 > "What would you like to do?
 > (A) **Share** a Revit model with my team for the first time.
 > (B) **Connect** to a shared central a teammate already uploaded.
@@ -51,9 +61,24 @@ the point.
 Then collect what that choice needs. Ask now; you will need it below.
 
 - **(A) Share:** the **absolute path** to the `.rvt`, a short lowercase **name** for the shared
-  central (e.g. `tower-central`), and the platform **Project ID** (in the project's settings and in
-  its URL in the dashboard). The file may or may not already be a workshared central — Step 3
-  checks. Either way **the user's original file is never modified**; a copy is uploaded.
+  central (e.g. `tower-central`), and the platform **Project ID**. The file may or may not already
+  be a workshared central — Step 3 checks. Either way **the user's original file is never
+  modified**; a copy is uploaded.
+
+  **Sharing a new central means a new project. Always send them to make one, every time:**
+
+  > "A shared central lives inside a platform project, so let's make one for it. Open
+  > **https://platform.thatopen.com/dashboard/projects**, create a project, then paste me either its
+  > id or just the URL of the page you land on — I can take the id out of the URL."
+
+  Take the **URL** if that is easier for them; the id is the segment after `/projects/`. Asking
+  somebody to copy a hex string off a settings page is a worse experience than asking for the
+  address bar, and it is the same information.
+
+  **You cannot do this part for them.** The CLI has no command to list projects and none to create
+  one, so there is no menu to offer and nothing to pick from — which also means: do not guess an id,
+  and do not reuse one you saw in `status`. Every command after this needs it, and a wrong one fails
+  with a 403 that reads like a permissions problem rather than a typo.
 
 - **(B) Connect:** identify the existing central by **one** of:
   - the **project folder id** of the central — the `revit-<name>` folder inside the project's
@@ -77,16 +102,24 @@ Do **not** ask for the access token yet. That is Step 1.
 
 2. **Token.** Ask for it, and say exactly where to get it:
 
-   > "To log in I need your That Open **access token**:
-   > 1. Open your dashboard — **production:** https://platform.thatopen.com ·
-   >    **dev:** https://dev.platform.thatopen.com (use the one that matches your team).
-   > 2. Go to **Data → API Tokens**.
-   > 3. **Create a new token**, copy it, and paste it here."
+   > "To log in I need a That Open Platform **access token**. You create it yourself:
+   > **https://platform.thatopen.com/dashboard/data → API Tokens → create → copy**, then paste it
+   > here."
 
    ```
    thatopen login --token <TOKEN>
    ```
-   Production is the default. For dev, add `--api-url https://dev.platform.thatopen.com`.
+
+   That command is already right: **it logs in to production, which is where everybody is.** Do not
+   ask the user to choose an environment — there is a dev platform, it is for the people building
+   That Open Platform, and they will say so without being asked.
+
+   **Log in even if the machine is already logged in.** A saved login is whoever used this machine
+   last. Never print the token back.
+
+   [Logging in to That Open Platform](https://raw.githubusercontent.com/ThatOpen/platform_services/main/docs/platform-token.md) is the short page for when this does not
+   go smoothly: what to do if the machine turns out to be pointed at dev, and why `Unauthorized` and
+   `403` mean different things.
 
 **Log in before Step 2**, not after: installing the add-in downloads a private package and needs
 these credentials.
@@ -101,6 +134,16 @@ thatopen revit status
 
 - Prints `"loaded": true` → the add-in is running. Check `addinVersion` is **1.2.17 or later**; if
   not, update it with the same command as below. Then go to Step 3.
+
+> **`status` also reports a `project`, a `doc` and a `central`. Do not use any of them.** They are
+> whatever this machine did last, which on a colleague's laptop or a shared machine is somebody
+> else's work. Say what you found and ask:
+>
+> > "This machine is still connected to project `<id>`, document `<doc>`. Do you want to keep
+> > working on that one, connect to a different project, or share a new model?"
+>
+> Publishing into the wrong project succeeds, looks completely normal, and puts somebody's model
+> somewhere their team cannot see it.
 - Errors *"The That Open Revit add-in is not running"* → work through (a), then (b).
 
 **(a) Is Revit 2026 open?** If not, launch it:
@@ -127,27 +170,30 @@ Re-run `thatopen revit status` every ten seconds or so until `"loaded": true`.
 
 ## Step 3 — Do the action
 
-### (A) Share a model — `inspect`, then `publish-central`
+### (A) Share a model — one command
 
 ```
-thatopen revit inspect --file "<FILE>"
+thatopen revit share --file "<FILE>" --project <PROJECT>
 ```
 
-- **`"isCentral": true`** → already a central. Tell the user you will upload a copy and their
-  original is untouched, then:
-  ```
-  thatopen revit publish-central --project <PROJECT> --doc <DOC> --file "<FILE>"
-  ```
-- **`"isCentral": false`** → a plain model. **Ask for consent first:** *"This file isn't a shared
-  central yet. To share it I need to turn it into one. I'll do that on a COPY, so your original
-  stays exactly as it is. Shall I go ahead?"* Only then:
-  ```
-  thatopen revit publish-central --project <PROJECT> --doc <DOC> --file "<FILE>" --convert
-  ```
-
-Publishing uploads the central and opens **the user's own local** in Revit. Success ends with
-`Published (…). Central: … (version N). Your original file was not modified.` Teammates connect with
-the folder id from the dashboard, or with `--project` and `--doc`.
+That is the whole of it. `share` installs the add-in if nothing is listening, starts Revit and
+waits for it, checks whether the file is already a central, publishes it, and opens the user's own
+local. It prints each of the five steps as it reaches them, so a long silence is always a step you
+can name.
+
+- **`--doc <name>`** is optional. Left out, it comes from the file name, kebab-cased.
+- **`--project`** takes the dashboard URL as happily as the id.
+- **The original file is never modified.** Everything happens on a copy, which is why `share` does
+  not need to ask before converting: there is nothing to lose. Say so rather than asking.
+- **It joins at the end on purpose.** Sharing a model and then carrying on in the original file is
+  the one reliable way to end up outside your own team.
+
+Steps 1 and 2 (CLI, login, add-in) still have to have happened: `share` installs the add-in but it
+cannot log in for somebody.
+
+If you need the pieces separately — a central that already exists, a different convert decision,
+scripting around it — they are still there: `thatopen revit inspect --file`, then
+`thatopen revit publish-central --project --doc --file [--convert]`, then `thatopen revit join`.
 
 ### (B) Connect to a central — `join`
 
@@ -224,11 +270,16 @@ anything that can produce the format can queue one. This package's job starts wh
 which is why nothing below asks where it came from.
 
 If the user asks how to send changes *from* their own tool — or you are being asked to write that
-tool — the format is documented: **[Writing a flow plugin](./flow-plugin-guide.md)** is the byte
-contract, and **[the architecture notes](./flow-architecture.md)** say why it is shaped that way.
+tool — the format is documented: **[Writing a flow plugin](https://raw.githubusercontent.com/ThatOpen/platform_services/main/docs/flow-plugin-guide.md)** is the byte
+contract, and **[the architecture notes](https://raw.githubusercontent.com/ThatOpen/platform_services/main/docs/flow-architecture.md)** say why it is shaped that way.
 Publishing a proposal is the smallest of the three jobs described there: it needs no ownership, no
 history, and no collaboration layer.
 
+If the tool is **Rhino**, the whole path is already written and worked through end to end:
+**[Rhino → Revit, start to finish](https://raw.githubusercontent.com/ThatOpen/platform_services/main/docs/rhino-interop-quickstart.md)**. Read that
+instead of assembling it from the two documents above — it covers installing the plug-in, driving
+Rhino without a keyboard, and the traps that cost a night.
+
 **This is where you use the add-in's local API** — the CLI has no proposal commands yet.
 
 **List what is waiting:**
@@ -279,18 +330,47 @@ in a status field and differently in a model.
 
 ## Step 7 — Offer them a viewer that shows the progress
 
-Once a team has been syncing for a few days, every sync is a commit and the platform is holding the
-whole history: who changed what, when, and the geometry as it was at each version. Nothing in Revit
-shows that back to them, and it is the question people ask first — *what has changed since Friday?*
+**Offer this as soon as the central exists — right after Step 3, before they start working.** Not
+at the end. Every sync from that moment on becomes a commit they can watch arrive, and setting it up
+costs the same on day one as on day thirty. Left to the end it sounds like an extra; offered at the
+start it is the thing that makes the rest visible.
 
-So offer it, rather than waiting to be asked:
+Every sync is a commit, and the platform keeps the lot: who changed what, when, and the geometry as
+it was at each version. Nothing in Revit shows that back, and it is the first thing people ask —
+*what has changed since Friday?*
 
-> "Everything you've synced is stored as a history. Would you like a viewer that shows it — pick any
+Say it plainly and wait:
+
+> "Everything you sync is stored as a history. Would you like a viewer that shows it — pick any
 > version and see what was created, modified and deleted, coloured in 3D?"
 
 If they say yes, that is an **app**, and building one is
-**[the platform AI quick start](./ai-quickstart.md)** — scaffold with the `app` template and follow
-it. What makes it a history viewer rather than an empty viewer is a built-in component that already
+**[the platform AI quick start](https://raw.githubusercontent.com/ThatOpen/platform_services/main/docs/ai-quickstart.md)** — scaffold with the `app` template and follow
+it.
+
+**Do not ask them how to add the panel.** Add a **new layout** called `History`, and leave the
+scaffold's own layouts alone. It is a two-line change, it keeps the app they were given intact, and
+it is the answer every time — asking hands somebody a UI decision about a screen they have not seen
+yet.
+
+```ts
+app.elements = {
+  ...app.elements,
+  history: () => html`<top-git-history></top-git-history>`,
+};
+```
+
+**For the layout, copy one of the scaffold's own panel layouts and swap its panel for `history`** —
+same side, same width, same shape. Do not choose a side and do not pick a width: the app already
+answered both, and the answer is written in `app.layouts` right there in `main.ts`.
+
+A panel that opens on the opposite side from every other one, at a different size, is the first
+thing anybody notices, and it reads as bolted on however good the contents are.
+
+For the layout's `icon`, use **`at-icons:git-branch`** — That Open's own icon set, and the branch
+mark is what the panel actually shows.
+
+What makes it a history viewer rather than an empty viewer is a built-in component that already
 exists, so nobody writes this part:
 
 - **`GitHistoryManager`** — the headless half. It reads `revitflow_history.json` and the per-commit