@seliseblocks/cli-os 0.2.10 → 0.2.11

package/dist/skills/blocks-data-storage/flows/object-management.md

@@ -1,124 +1,124 @@
-# Object management
-
-Use `blocks data files *` from a terminal and `blocksClient.data.directories` / `blocksClient.data.objects` / `blocksClient.data.files` in app code. Do not fall back to legacy `data.dms.*` helpers or raw HTTP.
-
-## Browse a directory
-
-Use the current `get-objects` operation with:
-
-- `parentDirectoryId` for a concrete directory, or `moduleName` to resolve a module's default directory when no parent id is supplied.
-- `cursor` from the previous response and `limit` from 1–200 (default 50).
-- `type: "directory" | "file"` to narrow results.
-- `search` for name filtering within that parent.
-
-The result contains `items`, `nextCursor`, `hasMore`, and `totalChildCount`. Each item has a lowercase `type` discriminator and permission flags. Continue while `hasMore` using `nextCursor`; access filtering can produce a short page even when more results remain.
-
-Use `search-objects` for a case-insensitive name search across descendants. Pass `query`, optional `directoryId`, optional type, cursor, and limit. Search text is treated literally rather than as a regular expression.
-
-```bash
-blocks data files list --parent-id <directoryId> --type file --limit 50 --json
-blocks data files search invoice --directory-id <directoryId> --json
-```
-
-```ts
-const page = await blocksClient.data.objects.list({ parentDirectoryId, limit: 50 });
-const matches = await blocksClient.data.objects.search({ query: "invoice", directoryId });
-```
-
-## Manage directories
-
-- **Create:** provide `name`, an existing `parentDirectoryId`, optional `description`, `configurationName`, and `allowedFileExtensions`. If the parent is empty but `moduleName` is present, the backend resolves the module default. Creating a true root uses a separate owner-only capability and should not be a normal app action.
-- **Read details:** get one directory by `directoryId`. The response includes path, ancestors, child counts, size, extension rules, inheritance, timestamps, and permissions.
-- **Update:** provide `directoryId` and optional `name`/`description`. Default directories cannot be renamed.
-- **Move:** provide `directoryId` and `targetDirectoryId`; an empty target means top level. Moving into self/descendants is rejected. Default directories cannot move.
-- **Delete:** send `permanent: false` for trash. Permanent deletion requires an empty directory. Default directories cannot be deleted.
-
-Directory names must be 1–255 characters, trimmed, not `.`/`..`, and contain no slash or backslash. Descriptions are limited to 2,000 characters.
-
-```bash
-blocks data files directory-create Contracts --parent-id <directoryId> \
-  --allowed-extensions pdf,docx --dry-run --json
-blocks data files directory-get <directoryId> --json
-blocks data files directory-update <directoryId> --name Agreements --dry-run --json
-blocks data files directory-move <directoryId> --target-directory-id <targetId> --dry-run --json
-blocks data files directory-delete <directoryId> --dry-run --json
-```
-
-Use the matching `blocksClient.data.directories.create/get/update/move/delete` methods in app code.
-
-## Manage files
-
-- **Rename:** needs Edit and a unique name in the current directory.
-- **Move:** needs Delete on the source file and Edit on the target directory. Stored bytes and versions stay in place.
-- **Copy:** needs View on the source and Edit on the target. The new file gets a new id; version rows reference the same immutable stored bytes. It inherits from the target. Set `copyAccessPolicies` only when the user intends to duplicate direct policy entries.
-- **Versions:** list newest-first with a cursor and limit 1–100. Creating a cloud version returns `versionNo` and `uploadUrl`; PUT the bytes to that URL without Blocks auth headers.
-
-Move/copy reject a target name collision and a file extension disallowed by the target directory.
-
-```bash
-blocks data files rename <fileId> --name final.pdf --dry-run --json
-blocks data files move <fileId> --target-directory-id <targetId> --dry-run --json
-blocks data files copy <fileId> --target-directory-id <targetId> --dry-run --json
-```
-
-Use `blocksClient.data.files.rename`, `.move`, and `.copy` in app code.
-
-## Trash and restore
-
-Use soft delete (`permanent: false`) to archive an item. List archived files/directories with `get-trash`, optionally filtering by type and paging with cursor/limit. Restore with `restore-from-trash`; permanently purge an archived item with `delete-from-trash` only after explicit approval.
-
-Restore returns the item to its original parent. Reads and mutations remain ACL-filtered while the item is archived.
-
-```bash
-blocks data files trash --type file --json
-blocks data files restore <resourceId> --dry-run --json
-blocks data files purge <resourceId> --dry-run --json
-```
-
-Use `blocksClient.data.objects.trash`, `.restore`, and `.deleteFromTrash` in app code.
-
-## Shared objects
-
-Use `get-shared-objects` for live items shared with the caller. It is cursor-paginated and may be filtered by `directory`/`file`. Owned objects are excluded. Direct or inherited allow entries for the current user, role, or organization qualify as shares.
-
-Use `share-object` for the common allow-only action. Provide:
-
-- `resourceId`
-- `resourceType`: `Directory` or `File`
-- `principalType`: `User`, `Role`, `Organization`, or `Everyone`
-- `principalId` for every type except `Everyone`
-- `permission`: `View`, `Download`, `Edit`, `Delete`, `Manage`, or `Owner`
-- optional future `expiresAt`
-
-Sharing requires Manage on the resource.
-
-```bash
-blocks data files shared --json
-blocks data files share <resourceId> --resource-type Directory \
-  --principal-type Role --principal-id editors --permission Edit --dry-run --json
-```
-
-Use `blocksClient.data.objects.shared` and `.share` in app code.
-
-## Advanced access policies
-
-Use the policy operations only for an access-management UI:
-
-- `get-access-policies` lists direct entries on a resource.
-- `grant-access` adds Allow or Deny with optional priority and expiry.
-- `update-access-policy` replaces an entry and requires its `policyItemId`.
-- `revoke-access-policy` removes an entry by `resourceId` and `policyItemId`.
-- `resolve-access` returns the caller's `canView`, `canDownload`, `canEdit`, `canDelete`, `canManage`, and `canOwner` flags.
-- `toggle-inheritance` changes whether ancestors participate in resolution.
-
-Enums are JSON strings, not guessed numeric values. Priority must be non-negative and expiry must be in the future.
-
-Policy guardrails:
-
-- Manage is required to change access.
-- A Deny aimed at the resource owner is rejected.
-- Turning inheritance off is rejected until the resource has a direct Allow entry, preventing an orphaned resource.
-- The request model for access-policy listing contains `includeInherited`, but the current controller does not use it; do not promise inherited entries in that response. Use `resolve-access` for effective permissions.
-- Object reads may return 404 instead of 403 to avoid revealing hidden ids.
-
-CLI access commands are `access-list`, `access-grant`, `access-update`, `access-revoke`, `access-resolve`, and `inheritance`. Their SDK equivalents are under `blocksClient.data.objects`.
+# Object management
+
+Use `blocks data files *` from a terminal and `blocksClient.data.directories` / `blocksClient.data.objects` / `blocksClient.data.files` in app code. Do not fall back to legacy `data.dms.*` helpers or raw HTTP.
+
+## Browse a directory
+
+Use the current `get-objects` operation with:
+
+- `parentDirectoryId` for a concrete directory, or `moduleName` to resolve a module's default directory when no parent id is supplied.
+- `cursor` from the previous response and `limit` from 1–200 (default 50).
+- `type: "directory" | "file"` to narrow results.
+- `search` for name filtering within that parent.
+
+The result contains `items`, `nextCursor`, `hasMore`, and `totalChildCount`. Each item has a lowercase `type` discriminator and permission flags. Continue while `hasMore` using `nextCursor`; access filtering can produce a short page even when more results remain.
+
+Use `search-objects` for a case-insensitive name search across descendants. Pass `query`, optional `directoryId`, optional type, cursor, and limit. Search text is treated literally rather than as a regular expression.
+
+```bash
+blocks data files list --parent-id <directoryId> --type file --limit 50 --json
+blocks data files search invoice --directory-id <directoryId> --json
+```
+
+```ts
+const page = await blocksClient.data.objects.list({ parentDirectoryId, limit: 50 });
+const matches = await blocksClient.data.objects.search({ query: "invoice", directoryId });
+```
+
+## Manage directories
+
+- **Create:** provide `name`, an existing `parentDirectoryId`, optional `description`, `configurationName`, and `allowedFileExtensions`. If the parent is empty but `moduleName` is present, the backend resolves the module default. Creating a true root uses a separate owner-only capability and should not be a normal app action.
+- **Read details:** get one directory by `directoryId`. The response includes path, ancestors, child counts, size, extension rules, inheritance, timestamps, and permissions.
+- **Update:** provide `directoryId` and optional `name`/`description`. Default directories cannot be renamed.
+- **Move:** provide `directoryId` and `targetDirectoryId`; an empty target means top level. Moving into self/descendants is rejected. Default directories cannot move.
+- **Delete:** send `permanent: false` for trash. Permanent deletion requires an empty directory. Default directories cannot be deleted.
+
+Directory names must be 1–255 characters, trimmed, not `.`/`..`, and contain no slash or backslash. Descriptions are limited to 2,000 characters.
+
+```bash
+blocks data files directory-create Contracts --parent-id <directoryId> \
+  --allowed-extensions pdf,docx --dry-run --json
+blocks data files directory-get <directoryId> --json
+blocks data files directory-update <directoryId> --name Agreements --dry-run --json
+blocks data files directory-move <directoryId> --target-directory-id <targetId> --dry-run --json
+blocks data files directory-delete <directoryId> --dry-run --json
+```
+
+Use the matching `blocksClient.data.directories.create/get/update/move/delete` methods in app code.
+
+## Manage files
+
+- **Rename:** needs Edit and a unique name in the current directory.
+- **Move:** needs Delete on the source file and Edit on the target directory. Stored bytes and versions stay in place.
+- **Copy:** needs View on the source and Edit on the target. The new file gets a new id; version rows reference the same immutable stored bytes. It inherits from the target. Set `copyAccessPolicies` only when the user intends to duplicate direct policy entries.
+- **Versions:** list newest-first with a cursor and limit 1–100. Creating a cloud version returns `versionNo` and `uploadUrl`; PUT the bytes to that URL without Blocks auth headers.
+
+Move/copy reject a target name collision and a file extension disallowed by the target directory.
+
+```bash
+blocks data files rename <fileId> --name final.pdf --dry-run --json
+blocks data files move <fileId> --target-directory-id <targetId> --dry-run --json
+blocks data files copy <fileId> --target-directory-id <targetId> --dry-run --json
+```
+
+Use `blocksClient.data.files.rename`, `.move`, and `.copy` in app code.
+
+## Trash and restore
+
+Use soft delete (`permanent: false`) to archive an item. List archived files/directories with `get-trash`, optionally filtering by type and paging with cursor/limit. Restore with `restore-from-trash`; permanently purge an archived item with `delete-from-trash` only after explicit approval.
+
+Restore returns the item to its original parent. Reads and mutations remain ACL-filtered while the item is archived.
+
+```bash
+blocks data files trash --type file --json
+blocks data files restore <resourceId> --dry-run --json
+blocks data files purge <resourceId> --dry-run --json
+```
+
+Use `blocksClient.data.objects.trash`, `.restore`, and `.deleteFromTrash` in app code.
+
+## Shared objects
+
+Use `get-shared-objects` for live items shared with the caller. It is cursor-paginated and may be filtered by `directory`/`file`. Owned objects are excluded. Direct or inherited allow entries for the current user, role, or organization qualify as shares.
+
+Use `share-object` for the common allow-only action. Provide:
+
+- `resourceId`
+- `resourceType`: `Directory` or `File`
+- `principalType`: `User`, `Role`, `Organization`, or `Everyone`
+- `principalId` for every type except `Everyone`
+- `permission`: `View`, `Download`, `Edit`, `Delete`, `Manage`, or `Owner`
+- optional future `expiresAt`
+
+Sharing requires Manage on the resource.
+
+```bash
+blocks data files shared --json
+blocks data files share <resourceId> --resource-type Directory \
+  --principal-type Role --principal-id editors --permission Edit --dry-run --json
+```
+
+Use `blocksClient.data.objects.shared` and `.share` in app code.
+
+## Advanced access policies
+
+Use the policy operations only for an access-management UI:
+
+- `get-access-policies` lists direct entries on a resource.
+- `grant-access` adds Allow or Deny with optional priority and expiry.
+- `update-access-policy` replaces an entry and requires its `policyItemId`.
+- `revoke-access-policy` removes an entry by `resourceId` and `policyItemId`.
+- `resolve-access` returns the caller's `canView`, `canDownload`, `canEdit`, `canDelete`, `canManage`, and `canOwner` flags.
+- `toggle-inheritance` changes whether ancestors participate in resolution.
+
+Enums are JSON strings, not guessed numeric values. Priority must be non-negative and expiry must be in the future.
+
+Policy guardrails:
+
+- Manage is required to change access.
+- A Deny aimed at the resource owner is rejected.
+- Turning inheritance off is rejected until the resource has a direct Allow entry, preventing an orphaned resource.
+- The request model for access-policy listing contains `includeInherited`, but the current controller does not use it; do not promise inherited entries in that response. Use `resolve-access` for effective permissions.
+- Object reads may return 404 instead of 403 to avoid revealing hidden ids.
+
+CLI access commands are `access-list`, `access-grant`, `access-update`, `access-revoke`, `access-resolve`, and `inheritance`. Their SDK equivalents are under `blocksClient.data.objects`.

package/dist/skills/blocks-frontend-local-https/SKILL.md

@@ -1,100 +1,100 @@
----
-name: blocks-frontend-local-https
-description: "Run a scaffolded (`blocks new web`) Blocks app locally over HTTPS on its real project domain — required for hosted IAM login, since plain HTTP or localhost never gets the session cookie. The scaffold already automates cert generation (npm run cert, no OpenSSL needed) and HTTPS serving via vite.config.ts. Covers running that flow, trusting the cert, the hosts-file entry, and troubleshooting. Use when running a scaffolded app over HTTPS, hitting 'SSO cookie not set' / Vite 'Blocked request' errors, trusting the dev cert, or asking why local login redirects back but doesn't stay signed in."
----
-
-# Blocks Frontend — Local HTTPS for a Scaffolded App
-
-This is the local dev loop for an app already created with `blocks new web` (see the blocks-onboarding skill for the scaffold command itself — this skill doesn't repeat it). The scaffold **already generates its own cert tooling**; nothing here is built from scratch, and nothing uses raw `openssl`/`curl`/`fetch`.
-
-## Why localhost doesn't work
-
-Browser login goes through the hosted Blocks IAM IdP flow (`blocksClient.auth.idp.redirectToProvider()` / `.callback()`), which finishes by IAM setting a **Secure, domain-scoped session cookie**. Browsers won't store or send that cookie on plain `http://localhost` — it has to be HTTPS, and it has to be on the project's real domain, or the cookie silently never lands and the app looks "logged in" for a second then bounces back to logged-out.
-
-## Where the domain comes from
-
-`--app-domain` on `blocks new web` is the app's real Blocks origin, e.g. `https://dbpdba.seliseblocks.com`. The generated `.env` keeps two derived values:
-
-- `VITE_BLOCKS_APP_DOMAIN` — the full value as passed, with scheme (`https://dbpdba.seliseblocks.com`).
-- `VITE_BLOCKS_DEV_HOST` — the same host with no scheme (`dbpdba.seliseblocks.com`), computed by the scaffold generator and used everywhere locally: hosts file, cert `commonName`/SAN, and `vite.config.ts`'s `server.host`/`allowedHosts`.
-
-You never need to look this up separately — it's already sitting in `.env` after scaffolding.
-
-## The flow
-
-```bash
-cd <appName>
-npm install
-npm run cert
-```
-
-`npm run cert` runs `scripts/generate-cert.mjs`, which reads `VITE_BLOCKS_DEV_HOST` from `.env` (or `process.env`, or an explicit `npm run cert -- <domain>` argument) and uses the `selfsigned` npm dependency to write `.cert/dev-key.pem` and `.cert/dev-cert.pem`, with `subjectAltName` covering the domain, `localhost`, and `127.0.0.1`. This is pure Node — it works from a plain PowerShell prompt with no OpenSSL and no Git Bash/WSL switch.
-
-Next, map the domain to your machine — add one line to the hosts file (needs admin/elevated):
-
-```text
-127.0.0.1 dbpdba.seliseblocks.com
-```
-
-Windows path: `C:\Windows\System32\drivers\etc\hosts` (edit as Administrator).
-
-Then:
-
-```bash
-npm run dev
-```
-
-`vite.config.ts` picks up `.cert/dev-key.pem` + `.cert/dev-cert.pem` automatically when both exist and serves HTTPS on `VITE_BLOCKS_DEV_HOST`:`VITE_BLOCKS_DEV_PORT` (default port `5173`, `strictPort: true` because the port is baked into the registered OIDC redirect URI). It also sets `allowedHosts` to that domain, working around Vite's default DNS-rebinding protection which otherwise 404s custom hosts with "Blocked request."
-
-Finally, open the app at:
-
-```text
-https://dbpdba.seliseblocks.com:5173
-```
-
-**Not** `http://`, **not** `localhost` — either one skips the cookie entirely even though the app loads.
-
-## Trusting the cert (optional but recommended)
-
-The cert is self-signed, so the browser shows a one-time warning until trusted. `npm run cert` prints the exact trust command for your OS when it finishes:
-
-- Windows (elevated prompt): `certutil -addstore -f Root .cert\dev-cert.pem`
-- macOS: `sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain .cert/dev-cert.pem`
-- Linux: `sudo cp .cert/dev-cert.pem /usr/local/share/ca-certificates/blocks-dev.crt && sudo update-ca-certificates`
-
-Restart the browser after trusting so it picks up the new trust store entry. `.cert/` is already gitignored by the scaffold — it's per-machine, never committed.
-
-## Still need a public OIDC client
-
-Local HTTPS alone doesn't make login succeed if no OIDC client is registered yet, or if its `redirect_uris` don't include this exact dev origin. That registration is portal-only (see blocks-onboarding's Gotchas) — out of scope here, but it's the next thing to check if HTTPS is right and login still fails. The redirect URI must match byte-for-byte, including `:5173`.
-
-## Gotchas
-
-**Custom app domain: the API base URL must share its registrable domain, or the cookie never lands.** `blocks new web --app-domain` isn't limited to `*.seliseblocks.com` — it also supports custom domains (e.g. `abc.slsblx.com`, `xyz.blx10.com`). On a custom domain, the hosted-login session cookie is only stored by the browser if `VITE_BLOCKS_API_URL` shares the app's registrable domain. Concretely:
-
-- `abc.slsblx.com` → `VITE_BLOCKS_API_URL` must be `https://blocksapi.slsblx.com`
-- `xyz.blx10.com` → `VITE_BLOCKS_API_URL` must be `https://blocksapi.blx10.com`
-
-If `VITE_BLOCKS_API_URL` is left at the default `https://api.seliseblocks.com` while the app itself runs on a custom domain, the browser treats the API as cross-site relative to the app and never stores the cookie — login still redirects back and *looks* successful, but cookie-based calls (`/iam/me`, organization switching, logout) silently fail. Check `VITE_BLOCKS_API_URL` in `.env` first whenever the app domain is not `*.seliseblocks.com` and auth-dependent calls are failing despite HTTPS and the cert being set up correctly.
-
-## Troubleshooting
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| Login redirects back but app shows logged-out | Opened on `http://` or `localhost` instead of the HTTPS dev host | Check the URL bar: must be `https://<VITE_BLOCKS_DEV_HOST>:5173` exactly |
-| Browser "not private" warning | Self-signed cert not trusted yet | Run the OS trust command `npm run cert` printed, then restart the browser |
-| Vite: "Blocked request. This host is not allowed" | `allowedHosts` doesn't include the host being requested — usually `.env`'s `VITE_BLOCKS_DEV_HOST` was edited/missing after scaffold, or the browser is hitting a different hostname than expected | Confirm `.env` has the right `VITE_BLOCKS_DEV_HOST` and that the URL bar matches it exactly |
-| Page doesn't load at all / DNS error | Hosts file entry missing or wrong | Add `127.0.0.1 <VITE_BLOCKS_DEV_HOST>` to `C:\Windows\System32\drivers\etc\hosts` (as Administrator) |
-| `npm run cert` errors "No domain given" | `.env` missing or `VITE_BLOCKS_DEV_HOST` not set | Confirm `.env` exists with `VITE_BLOCKS_DEV_HOST=<host>`, or run `npm run cert -- <domain>` explicitly |
-| `npm run dev` fails to bind the port | Port 5173 already in use (dev server uses `strictPort`, won't fall back) | Free port 5173, or the port is fixed because it's part of the registered OIDC redirect URI — don't just change it without updating the OIDC client too |
-| HTTPS works, cert trusted, login still fails | No OIDC client registered yet, or its redirect URI doesn't match this origin exactly | Register/update the public OIDC client in the portal with `https://<VITE_BLOCKS_DEV_HOST>:5173/login/callback` as a redirect URI (portal-only, see blocks-onboarding) |
-| Works for one dev, fails for a teammate | Each machine needs its own cert + hosts entry — `.cert/` is gitignored on purpose | Teammate runs `npm run cert` and adds the hosts entry on their own machine |
-
-## Example trigger prompts
-
-- "Run my app locally over HTTPS on its real domain so SSO works"
-- "My local login isn't working — it just bounces back to the login page"
-- "How do I set up the dev cert for this scaffolded app?"
-- "I'm getting 'Blocked request. This host is not allowed' from Vite"
-- "Do I need OpenSSL to run npm run cert on Windows?"
-- "Why does login work in production but not on localhost?"
+---
+name: blocks-frontend-local-https
+description: "Run a scaffolded (`blocks new web`) Blocks app locally over HTTPS on its real project domain — required for hosted IAM login, since plain HTTP or localhost never gets the session cookie. The scaffold already automates cert generation (npm run cert, no OpenSSL needed) and HTTPS serving via vite.config.ts. Covers running that flow, trusting the cert, the hosts-file entry, and troubleshooting. Use when running a scaffolded app over HTTPS, hitting 'SSO cookie not set' / Vite 'Blocked request' errors, trusting the dev cert, or asking why local login redirects back but doesn't stay signed in."
+---
+
+# Blocks Frontend — Local HTTPS for a Scaffolded App
+
+This is the local dev loop for an app already created with `blocks new web` (see the blocks-onboarding skill for the scaffold command itself — this skill doesn't repeat it). The scaffold **already generates its own cert tooling**; nothing here is built from scratch, and nothing uses raw `openssl`/`curl`/`fetch`.
+
+## Why localhost doesn't work
+
+Browser login goes through the hosted Blocks IAM IdP flow (`blocksClient.auth.idp.redirectToProvider()` / `.callback()`), which finishes by IAM setting a **Secure, domain-scoped session cookie**. Browsers won't store or send that cookie on plain `http://localhost` — it has to be HTTPS, and it has to be on the project's real domain, or the cookie silently never lands and the app looks "logged in" for a second then bounces back to logged-out.
+
+## Where the domain comes from
+
+`--app-domain` on `blocks new web` is the app's real Blocks origin, e.g. `https://dbpdba.seliseblocks.com`. The generated `.env` keeps two derived values:
+
+- `VITE_BLOCKS_APP_DOMAIN` — the full value as passed, with scheme (`https://dbpdba.seliseblocks.com`).
+- `VITE_BLOCKS_DEV_HOST` — the same host with no scheme (`dbpdba.seliseblocks.com`), computed by the scaffold generator and used everywhere locally: hosts file, cert `commonName`/SAN, and `vite.config.ts`'s `server.host`/`allowedHosts`.
+
+You never need to look this up separately — it's already sitting in `.env` after scaffolding.
+
+## The flow
+
+```bash
+cd <appName>
+npm install
+npm run cert
+```
+
+`npm run cert` runs `scripts/generate-cert.mjs`, which reads `VITE_BLOCKS_DEV_HOST` from `.env` (or `process.env`, or an explicit `npm run cert -- <domain>` argument) and uses the `selfsigned` npm dependency to write `.cert/dev-key.pem` and `.cert/dev-cert.pem`, with `subjectAltName` covering the domain, `localhost`, and `127.0.0.1`. This is pure Node — it works from a plain PowerShell prompt with no OpenSSL and no Git Bash/WSL switch.
+
+Next, map the domain to your machine — add one line to the hosts file (needs admin/elevated):
+
+```text
+127.0.0.1 dbpdba.seliseblocks.com
+```
+
+Windows path: `C:\Windows\System32\drivers\etc\hosts` (edit as Administrator).
+
+Then:
+
+```bash
+npm run dev
+```
+
+`vite.config.ts` picks up `.cert/dev-key.pem` + `.cert/dev-cert.pem` automatically when both exist and serves HTTPS on `VITE_BLOCKS_DEV_HOST`:`VITE_BLOCKS_DEV_PORT` (default port `5173`, `strictPort: true` because the port is baked into the registered OIDC redirect URI). It also sets `allowedHosts` to that domain, working around Vite's default DNS-rebinding protection which otherwise 404s custom hosts with "Blocked request."
+
+Finally, open the app at:
+
+```text
+https://dbpdba.seliseblocks.com:5173
+```
+
+**Not** `http://`, **not** `localhost` — either one skips the cookie entirely even though the app loads.
+
+## Trusting the cert (optional but recommended)
+
+The cert is self-signed, so the browser shows a one-time warning until trusted. `npm run cert` prints the exact trust command for your OS when it finishes:
+
+- Windows (elevated prompt): `certutil -addstore -f Root .cert\dev-cert.pem`
+- macOS: `sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain .cert/dev-cert.pem`
+- Linux: `sudo cp .cert/dev-cert.pem /usr/local/share/ca-certificates/blocks-dev.crt && sudo update-ca-certificates`
+
+Restart the browser after trusting so it picks up the new trust store entry. `.cert/` is already gitignored by the scaffold — it's per-machine, never committed.
+
+## Still need a public OIDC client
+
+Local HTTPS alone doesn't make login succeed if no OIDC client is registered yet, or if its `redirect_uris` don't include this exact dev origin. That registration is portal-only (see blocks-onboarding's Gotchas) — out of scope here, but it's the next thing to check if HTTPS is right and login still fails. The redirect URI must match byte-for-byte, including `:5173`.
+
+## Gotchas
+
+**Custom app domain: the API base URL must share its registrable domain, or the cookie never lands.** `blocks new web --app-domain` isn't limited to `*.seliseblocks.com` — it also supports custom domains (e.g. `abc.slsblx.com`, `xyz.blx10.com`). On a custom domain, the hosted-login session cookie is only stored by the browser if `VITE_BLOCKS_API_URL` shares the app's registrable domain. Concretely:
+
+- `abc.slsblx.com` → `VITE_BLOCKS_API_URL` must be `https://blocksapi.slsblx.com`
+- `xyz.blx10.com` → `VITE_BLOCKS_API_URL` must be `https://blocksapi.blx10.com`
+
+If `VITE_BLOCKS_API_URL` is left at the default `https://api.seliseblocks.com` while the app itself runs on a custom domain, the browser treats the API as cross-site relative to the app and never stores the cookie — login still redirects back and *looks* successful, but cookie-based calls (`/iam/me`, organization switching, logout) silently fail. Check `VITE_BLOCKS_API_URL` in `.env` first whenever the app domain is not `*.seliseblocks.com` and auth-dependent calls are failing despite HTTPS and the cert being set up correctly.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Login redirects back but app shows logged-out | Opened on `http://` or `localhost` instead of the HTTPS dev host | Check the URL bar: must be `https://<VITE_BLOCKS_DEV_HOST>:5173` exactly |
+| Browser "not private" warning | Self-signed cert not trusted yet | Run the OS trust command `npm run cert` printed, then restart the browser |
+| Vite: "Blocked request. This host is not allowed" | `allowedHosts` doesn't include the host being requested — usually `.env`'s `VITE_BLOCKS_DEV_HOST` was edited/missing after scaffold, or the browser is hitting a different hostname than expected | Confirm `.env` has the right `VITE_BLOCKS_DEV_HOST` and that the URL bar matches it exactly |
+| Page doesn't load at all / DNS error | Hosts file entry missing or wrong | Add `127.0.0.1 <VITE_BLOCKS_DEV_HOST>` to `C:\Windows\System32\drivers\etc\hosts` (as Administrator) |
+| `npm run cert` errors "No domain given" | `.env` missing or `VITE_BLOCKS_DEV_HOST` not set | Confirm `.env` exists with `VITE_BLOCKS_DEV_HOST=<host>`, or run `npm run cert -- <domain>` explicitly |
+| `npm run dev` fails to bind the port | Port 5173 already in use (dev server uses `strictPort`, won't fall back) | Free port 5173, or the port is fixed because it's part of the registered OIDC redirect URI — don't just change it without updating the OIDC client too |
+| HTTPS works, cert trusted, login still fails | No OIDC client registered yet, or its redirect URI doesn't match this origin exactly | Register/update the public OIDC client in the portal with `https://<VITE_BLOCKS_DEV_HOST>:5173/login/callback` as a redirect URI (portal-only, see blocks-onboarding) |
+| Works for one dev, fails for a teammate | Each machine needs its own cert + hosts entry — `.cert/` is gitignored on purpose | Teammate runs `npm run cert` and adds the hosts entry on their own machine |
+
+## Example trigger prompts
+
+- "Run my app locally over HTTPS on its real domain so SSO works"
+- "My local login isn't working — it just bounces back to the login page"
+- "How do I set up the dev cert for this scaffolded app?"
+- "I'm getting 'Blocked request. This host is not allowed' from Vite"
+- "Do I need OpenSSL to run npm run cert on Windows?"
+- "Why does login work in production but not on localhost?"