@thatopen/services 0.6.0 → 0.7.0

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

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,6 +37,10 @@ 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.
 
 ---
 
@@ -51,9 +55,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 +96,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 +128,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:
@@ -224,11 +261,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 +321,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.
+
+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?*
 
-So offer it, rather than waiting to be asked:
+Say it plainly and wait:
 
-> "Everything you've synced is stored as a history. Would you like a viewer that shows it — pick any
+> "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