@seliseblocks/cli-os 0.2.2 → 0.2.4

package/dist/skills/blocks-data-storage/SKILL.md

@@ -1,161 +1,253 @@
 ---
 name: blocks-data-storage
-description: "Store and serve files on a SELISE Blocks project: presigned/local-storage upload, download, folder browsing, tags/metadata, and delete, via the blocks CLI ('data files *') for admin/scripting or the @seliseblocks/client SDK ('data.files'/'data.dms') for in-app upload/download flows. Use for prompts like upload a file and get a download link, attach an image to a record, create a folder, let users download a file, tag or delete an uploaded file. Separate from the data model — schemas/records live in blocks-data-gateway-configuration/-crud; this covers files/DMS only, implementation-mode, SDK-driven."
+description: "Build file and document-management features on SELISE Blocks Data: upload/download, directory trees, cursor-paginated browsing and search, file versions, rename/move/copy, soft delete/trash/restore, sharing, access policies, and inheritance. Use for attachments, file browsers, folders, shared files, permissions, or version history. Use 'blocks data files *' for terminal/admin work and @seliseblocks/client data.files/data.directories/data.objects for app code."
 ---
 
-# Blocks Data — Storage (Files / DMS)
+# Blocks Data — Storage
 
-Storage is DMS (document management system). Two ways to reach it, pick based on what the user is actually doing:
+Treat storage as one permission-aware object tree containing **directories** and **files**. Uploading a new file now creates the file object in that tree; there is no second DMS registration step.
 
-- **`blocks data files *` (CLI)** — admin tasks, one-off scripts, or anything the user is doing from a terminal/agent context rather than inside a running app.
-- **`@seliseblocks/client`'s `data.files` / `data.dms` namespaces (SDK)** — wiring upload/download/browse into actual app code (a React component, a form submit handler).
+Use:
 
-Both surfaces do the same work; which one to use is about *where the code runs*, not a capability gap — unlike some other Data resources, this one has full CLI coverage.
+- **`blocks data files *`** for supported terminal/admin operations.
+- **`@seliseblocks/client`** for app code. Use the shared `blocksClient` created by blocks-onboarding.
+- **blocks-storage-configuration** only to manage the named provider configuration used by `configurationName`.
 
-**Prerequisite:** a project is selected (`blocks use <tenantId>`). For the SDK path, a frontend also needs to be scaffolded. If login/project state is unknown, or there's no app to write SDK code into yet, run the blocks-onboarding skill first — it gets `blocks new web` scaffolding in place (React 18 + TypeScript + Vite + Tailwind + Radix + TanStack Query + a single `@seliseblocks/client` instance). The SDK examples below assume that scaffold's shared client, conventionally exported as `blocksClient` from `src/lib/blocks/client.ts`.
+Select a project first with `blocks use <tenantId>`. If login/project state or the shared client setup is unknown, use blocks-onboarding before this skill.
 
-```ts
-import { blocksClient } from "../lib/blocks/client";
-const { files, dms } = blocksClient.data;
-```
+Store the returned `fileId` in a Data record when attaching a file to domain data. Use blocks-data-gateway-crud for the record mutation.
 
-Store a file here and keep its returned `fileId` in a schema field (see the blocks-data-gateway-crud skill) to associate it with a record.
+## Choose the surface
 
-## CLI quick reference
+The current CLI and SDK follow the backend's file, directory, and object resource groups.
 
 ```bash
-# Cloud storage (pre-signed URL), two steps
-blocks data files presigned-upload-url --name invoice.pdf --access-modifier Public --json
-blocks data files upload-to-url --url "<uploadUrl from above>" --file ./invoice.pdf --content-type application/pdf --yes --json
+blocks --version
+blocks data files --help
+```
 
-# Local storage, one step
-blocks data files upload-to-local-storage --file ./invoice.pdf --access-modifier Public --yes --json
+- Use `blocks data files *` for terminal/admin work and inspect `blocks --help` for exact flags.
+- Use `blocksClient.data.files` for bytes, metadata, versions, and file operations.
+- Use `blocksClient.data.directories` for directory create/get/update/delete/move.
+- Use `blocksClient.data.objects` for browse/search/trash/shared/restore/share/access/inheritance.
 
-# Register the uploaded file in a DMS folder (upload alone doesn't do this)
-blocks data files dms-upload --file-storage-id <fileId> --artifact-name invoice.pdf --yes --json
+Legacy `data.dms.*`, `dms-upload`, `dms-list`, `create-folder`, and `delete-folder` wrappers are retired. Uploads need no registration call.
 
-# Read it back
-blocks data files dms-list --parent-id "" --json
-blocks data files get <fileId> --json
+## Upload a new file
 
-# Folders, metadata, cleanup
-blocks data files create-folder Invoices --yes --json
-blocks data files update-additional-info <fileId> --additional-properties '{"status":"reviewed"}' --yes --json
-blocks data files delete <fileId> --yes --json
-```
+Choose one path from the project's storage configuration.
+
+| Provider category | Sequence |
+|---|---|
+| Cloud object storage | request a pre-signed URL, then PUT the bytes to it |
+| Local/SFTP storage | send one authenticated multipart upload |
+
+Both paths create the file object and initial version directly. Do not call `dms-upload` afterward.
 
-Same two upload paths as the SDK section below (pick based on the project's storage backend, not per-call), same `--dry-run`-before-`--yes` discipline as every other `blocks` mutation.
+### Cloud upload from the CLI
 
-**Shortcut:** `blocks data files upload --file ./invoice.pdf --yes --json` composes the manual sequence above into one command — presign + PUT + `dms.uploadFiles` registration for cloud storage, or add `--local-storage` for the one-step local-storage path (uploads only, no DMS registration in that case). Same relationship as `data sync` is to the manual schema/rules/reload sequence elsewhere in this skill pack: reach for the manual steps when you need to inspect or reuse an intermediate result (e.g. the presigned URL itself), reach for `upload` when you just want the file stored.
+Prefer the composed command. It previews and confirms both metadata creation and the provider PUT:
 
-## Two upload paths — pick one per deployment
+```bash
+blocks data files upload --file ./invoice.pdf --parent-id <directoryId> \
+  --configuration-name Default --access-modifier Private --dry-run --json
+blocks data files upload --file ./invoice.pdf --parent-id <directoryId> \
+  --configuration-name Default --access-modifier Private --yes --json
+```
 
-A project's storage is backed by either cloud object storage (Azure Blob, S3, etc.) or local storage on the Blocks Data host. Which one applies is a property of the project's storage configuration, not something the frontend chooses per call — but the SDK exposes a distinct method for each:
+Use the two explicit commands only when the intermediate upload URL is required:
 
-| Deployment | Call sequence |
-|---|---|
-| **Cloud storage** (pre-signed URL) | `files.presignedUploadUrl(...)` → `files.uploadToUrl(...)` |
-| **Local storage** | `files.uploadToLocalStorage(...)` (one call, no presign step) |
+```bash
+blocks data files presigned-upload-url \
+  --name invoice.pdf \
+  --parent-directory-id <directoryId> \
+  --configuration-name Default \
+  --access-modifier Private \
+  --dry-run --json
+blocks data files presigned-upload-url \
+  --name invoice.pdf \
+  --parent-directory-id <directoryId> \
+  --configuration-name Default \
+  --access-modifier Private \
+  --yes --json
+
+blocks data files upload-to-url \
+  --url "<uploadUrl>" \
+  --file ./invoice.pdf \
+  --content-type application/pdf \
+  --dry-run --json
+blocks data files upload-to-url \
+  --url "<uploadUrl>" \
+  --file ./invoice.pdf \
+  --content-type application/pdf \
+  --yes --json
+```
 
-Both are followed by the same registration step, `dms.uploadFiles(...)`, if the file needs to show up in a DMS folder.
+The presign response contains `uploadUrl`, `fileId`, and `isSuccess`. The first call creates the file metadata/version; the PUT fills its object-storage key. Handle PUT failure explicitly because it can leave metadata for missing bytes.
 
-**Where that configuration lives:** `blocks storage config get/list/save/delete` (a separate top-level command group, not `data files`) reads/writes the named storage configuration itself — host, port, credentials, region/endpoint or connection string, and strategy — i.e. which provider a given `configurationName` points at, cloud or local. This skill only covers *using* that config name when uploading; managing the config's own fields is out of scope here — see the blocks-storage-configuration skill.
+When `parentDirectoryId` is empty, the cloud upload resolves `moduleName` to that module's default directory. The backend default is module value `8` (`Default_Construct`), but pass the intended module or a concrete directory id instead of relying on that default.
 
-## Step 1a (cloud) — get a pre-signed upload URL
+### Cloud upload from app code
 
 ```ts
-const presign = await files.presignedUploadUrl({
+const presign = await blocksClient.data.files.presignedUploadUrl({
   name: "invoice.pdf",
-  contentType: "application/pdf",
-  configurationName: "Default",       // example only — confirm the storage config name for this project
-  moduleName: 3,                      // example only — confirm the module value expected by this project
-  parentDirectoryId: "",              // required — "" for root, or a folder id; never omit/null
-  accessModifier: "Public"            // "Public" (readable without auth) or "Private"
+  parentDirectoryId: directoryId,
+  configurationName: "Default",
+  accessModifier: "Private",
+  tags: "invoice,2026",
 });
-```
 
-It returns the pre-signed `uploadUrl` plus a `fileId` you'll need for the next steps — the method's return type is `Promise<unknown>`, so read the exact response shape at runtime rather than assuming a typed contract. Note `contentType` in this request is not forwarded to the presign call itself (the normalizer drops it); pass it again to `uploadToUrl` below so the PUT gets the right `Content-Type` header. Treat `configurationName` and `moduleName` values as project-specific unless the tenant's storage configuration says otherwise.
+if (!presign || typeof presign !== "object") {
+  throw new Error("Unexpected upload response");
+}
 
-## Step 1b (cloud) — PUT the binary to that URL
+const result = presign as {
+  uploadUrl: string;
+  fileId: string;
+  isSuccess: boolean;
+  errors?: Record<string, string>;
+};
 
-```ts
-await files.uploadToUrl({
-  url: presign.uploadUrl,
-  body: fileBlob,              // Blob | ArrayBuffer | ArrayBufferView | ReadableStream
-  contentType: "application/pdf"
+if (!result.isSuccess) throw new Error(JSON.stringify(result.errors));
+
+await blocksClient.data.files.uploadToUrl({
+  url: result.uploadUrl,
+  body: file,
+  contentType: file.type || "application/octet-stream",
 });
 ```
 
-This is the one call in the whole skill that is **provider-direct, not a Blocks API call** — it sends **no `x-blocks-key` and no bearer token**. It PUTs straight to the storage provider's pre-signed URL. If you don't set your own `x-ms-blob-type` header, the SDK adds `x-ms-blob-type: Blockblob` for you (Azure's block-blob upload header); verify that this matches the storage provider and signed-URL policy for the project rather than assuming every provider ignores extra headers.
+`uploadToUrl` is provider-direct and sends no bearer token or `x-blocks-key`. The SDK adds Azure's `x-ms-blob-type: Blockblob` header unless overridden; ensure that header matches the signed provider policy.
 
-## Step 1 (local storage) — the one-call alternative
+### Local-storage upload
 
-For local-storage-backed deployments, skip the presign/PUT pair entirely and upload straight through Blocks Data:
+```bash
+blocks data files upload-to-local-storage \
+  --file ./invoice.pdf \
+  --parent-directory-id <directoryId> \
+  --configuration-name Default \
+  --access-modifier Private \
+  --dry-run --json
+blocks data files upload-to-local-storage \
+  --file ./invoice.pdf \
+  --parent-directory-id <directoryId> \
+  --configuration-name Default \
+  --access-modifier Private \
+  --yes --json
+```
 
 ```ts
-await files.uploadToLocalStorage({
-  name: "invoice.pdf",
-  file: fileBlob,               // Blob | File
+const uploaded = await blocksClient.data.files.uploadToLocalStorage({
+  name: file.name,
+  file,
+  parentDirectoryId: directoryId,
   configurationName: "Default",
-  parentDirectoryId: "",
-  accessModifier: "Public",
-  tags: ["invoice", "2026"]
+  accessModifier: "Private",
+  tags: ["invoice", "2026"],
 });
 ```
 
-The SDK builds a multipart `FormData` body for you (`File`, `Name`, `ItemId`, `MetaData`, `ParentDirectoryId`, `Tags`, `AccessModifier`, `ConfigurationName`, `AdditionalProperties[key]`) and sends it as a normal authenticated Blocks API call (`x-blocks-key` + bearer, unlike the pre-signed PUT above).
+This call creates the file object and uploads version 1 in one request. Unlike cloud presign, an empty local `parentDirectoryId` stays at the top level; it is not resolved through `moduleName`.
+
+## Add a file version
 
-## Step 2 — register the file in a DMS folder
+Supplying an existing `itemId` to either upload flow creates another version after the caller passes the file's Edit check. For cloud storage, the dedicated command/method returns another pre-signed URL:
 
-Neither upload path above makes a file appear in a document folder by itself — that's a separate registration call:
+```bash
+blocks data files versions <fileId> --limit 25 --json
+blocks data files create-version <fileId> --configuration-name Default --dry-run --json
+blocks data files create-version <fileId> --configuration-name Default --yes --json
+```
 
 ```ts
-await dms.uploadFiles({
-  upload: [{
-    fileStorageId: presign.fileId,   // the fileId from presignedUploadUrl (or the equivalent id from uploadToLocalStorage's response)
-    artifactName: "invoice.pdf",
-    parentId: "",                    // "" for root, or a folder id
-    tags: ["invoice"]
-  }]
-});
+const history = await blocksClient.data.files.versions({ fileId, limit: 25 });
+const next = await blocksClient.data.files.createVersion({ fileId, configurationName: "Default" });
 ```
 
-Despite the method's name suggesting a binary upload, this is the DMS *registration* call — the bytes are already stored by Step 1a/1b or Step 1. `upload` is an array, so multiple files can be registered into folders in one call.
+Version history is newest-first and cursor-paginated. Use the returned opaque `nextCursor`; the current backend uses the last version number internally, but callers must not construct cursors. Limits are 1–100, default 25.
 
-## Step 3 — read it back
+## Read and download
+
+```bash
+blocks data files get <fileId> --configuration-name Default --json
+blocks data files get <fileId> --version <versionNo> --configuration-name Default --json
+blocks data files get-many <fileId...> --configuration-name Default --json
+```
 
 ```ts
-const folder = await dms.list({ parentId: "", take: 20 });
-const meta = await files.get(presign.fileId, { configurationName: "Default" });
+const file = await blocksClient.data.files.get(fileId, {
+  configurationName: "Default",
+  version: 2,
+});
+```
+
+The response includes a download URL plus metadata. Download requires the caller's Download permission. Access-denied reads may deliberately look like missing resources so clients cannot probe hidden object ids.
+
+## Directory and object workflows
+
+For browsing, directories, search, move/copy/rename, trash, sharing, and ACL behavior, read [flows/object-management.md](flows/object-management.md).
+
+## Update custom metadata
+
+```bash
+blocks data files update-additional-info <fileId> \
+  --additional-properties '{"status":"reviewed"}' \
+  --dry-run --json
+blocks data files update-additional-info <fileId> \
+  --additional-properties '{"status":"reviewed"}' \
+  --yes --json
 ```
 
-`dms.list` returns the combined folder+file listing for a `parentId` (`""` = root), with `searchKey`/`skip`/`take` for search and paging. The same endpoint is also reachable as `files.listFolder(...)` — they're identical calls, `dms.list` is the more discoverable name for folder-browsing UI. `files.get` confirms a specific upload landed: a successful response with a non-null `url` (download link) and matching `name`/size means the file is stored.
+This updates `additionalProperties`; it does not rename, move, tag, or version the file.
+
+## Delete safely
+
+Deletion now distinguishes trash from permanent removal:
+
+- `permanent: false` archives the file or directory so it can be restored.
+- `permanent: true` removes it for good.
+- The backend default is **`true`** when `permanent` is omitted.
+
+The CLI defaults to safe soft deletion. Add `--permanent` only after explicit approval.
+
+```bash
+blocks data files delete <fileId> --dry-run --json
+blocks data files delete <fileId> --yes --json
+blocks data files delete <fileId> --permanent --dry-run --json
+```
+
+In app code, send the choice explicitly: `blocksClient.data.files.delete({ fileId, permanent: false })`.
+
+## Permission model
+
+Every storage request passes two checks:
+
+1. The endpoint permission permits that class of action.
+2. The object ACL permits the action on that specific file/directory.
 
-## Other file operations
+Capabilities are ordered: `View`, `Download`, `Edit`, `Delete`, `Manage`, `Owner`. Higher capabilities imply lower ones. Directory children inherit ancestor access while `inheritsParentAccess` is true. New files inherit from their directory.
 
-- **`files.getMany({ fileIds, configurationName })`** — batch read instead of one `files.get` per attachment.
-- **`files.info({ page, pageSize, sort, filter })`** — paged file metadata/listing for storage-browser UIs; unlike `presignedUploadUrl`, the SDK does not remap these field names to PascalCase — pass exactly what your app builds.
-- **`files.updateAdditionalInfo({ itemId, additionalProperties })`** — attach searchable metadata to an uploaded file, e.g. a business reference or workflow status.
-- **`files.delete({ fileId, configurationName?, eventQueueName? })`** — delete a file.
-- **`dms.createFolder({ artifactName, parentId?, configurationName? })`** / **`dms.deleteFolder({ folderId, configurationName? })`** — DMS folder management.
+Do not infer permission from a visible button or endpoint grant. Render actions from each object's returned `permissions` flags and still handle 403/404 races.
 
 ## Gotchas
 
-- **Terminal/admin task → CLI (`data files *`); app code → SDK.** Both exist and both are fully supported; don't default to writing a throwaway script against the SDK for something the CLI already does in one command, and don't reach for `blocks` from inside a React component.
-- **`--module-name` / `moduleName` and `--parent-directory-id` / `parentDirectoryId` on the presigned-upload-url call** — optional in the CLI/SDK types, but the underlying endpoint may require them for a given project/storage setup. Confirm the expected module value with the project's storage configuration, and always send a `parentDirectoryId` value (`""` for root) when the endpoint requires a parent folder value — the CLI command defaults it to `""` automatically if you omit `--parent-directory-id`.
-- **The pre-signed PUT is the one call with no Blocks auth.** `uploadToUrl` sends no `x-blocks-key` and no bearer token by design — everything else in this skill (`presignedUploadUrl`, `uploadToLocalStorage`, `dms.*`, `files.get`/`getMany`/`info`/`delete`) is a normal authenticated Blocks API call.
-- **Upload ≠ visible in a folder.** `uploadToUrl`/`uploadToLocalStorage` only gets the bytes stored; call `dms.uploadFiles` afterward if the file needs to appear under a DMS folder.
-- **Most file/DMS methods return `Promise<unknown>`.** The SDK doesn't hand you a typed response for this surface — check the actual JSON shape at runtime (e.g. log the presign response once) rather than assuming field names beyond what's documented here.
-- **`accessModifier`** is `"Public"` (readable without auth) or `"Private"` — decide per file, not per project.
-- Don't confuse this with the data model: a file's `fileId` is just a string you store in a schema field via **blocks-data-gateway-crud**; this skill never touches schemas.
-
-## Example trigger prompts
-
-- "Upload a PDF and get a download link." → CLI (`data files presigned-upload-url` + `upload-to-url`, or `upload-to-local-storage`) for a one-off; SDK if it's a feature in the app.
-- "Attach an image to this record." (upload via CLI or SDK, then store the `fileId` via blocks-data-gateway-crud)
-- "Let users download this file from the app." → SDK, this is in-app behavior.
-- "Create a folder and list its contents." → `data files create-folder` + `data files dms-list`.
-- "Get a presigned upload URL for a cloud storage upload." → `data files presigned-upload-url`.
-- "This deployment uses local storage — how do I upload a file?" → `data files upload-to-local-storage`.
-- "Tag this uploaded file with a status so it's searchable later." → `data files update-additional-info`.
-- "Delete this file / delete this folder." → `data files delete` / `data files delete-folder`.
+- Upload now creates the visible file object; legacy DMS registration is wrong and may fail after the bytes were successfully PUT.
+- Cloud presign creates metadata before the provider PUT. Treat the two steps as a recoverable workflow and surface partial failure.
+- A name must contain an allowed extension. Directories may restrict extensions.
+- Names are unique within a directory. File move/copy can fail on a name conflict or extension policy.
+- `Private` is the safe default. Use `Public` only when unauthenticated download is intended.
+- `configurationName` selects an existing provider record; it does not configure storage.
+- Most legacy file SDK methods return `Promise<unknown>`; validate responses at the boundary.
+- Never send Blocks auth headers to a pre-signed provider URL.
+- Never use a raw API call to work around a missing CLI/SDK wrapper; update the client surface first.
+
+## Example triggers
+
+- "Upload this PDF into the Contracts folder."
+- "Build a file browser with folders and search."
+- "Show files shared with the current user."
+- "Move this file to trash and let users restore it."
+- "Add version history and upload a replacement version."
+- "Share this directory with a role and let its children inherit access."
+- "Move, copy, or rename a file."

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

@@ -0,0 +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`.

package/dist/skills/blocks-iam-sso-oidc-configuration/SKILL.md

@@ -29,23 +29,36 @@ All of these commands are project-scoped: they need a selected project (`blocks
    ```
    blocks auth oidc-clients save \
      --client-display-name "<app name>" \
+     --client-type public \
      --redirect-uris "https://<app-domain>/login/callback" \
      --require-pkce --active \
      --scope "openid profile" \
      --register-as-identity-provider \
      [--dry-run] [--yes]
    ```
-   This mirrors exactly what `blocks new web`'s interactive OIDC-client prompt does when scaffolding a new web app. `--register-as-identity-provider` is what turns this from "just an OIDC client" into something the hosted-login redirect flow (`auth.idp.redirectToProvider()` / `auth.idp.callback()`) can authenticate against — per the CLI's own scaffold help text, this registers the client "as a Blocks OIDC identity provider" in the same call. For the common case (your own app logging its own users in via Blocks-hosted login), this single command is usually the entire provisioning step — `blocks new web` never calls `auth idp create` separately.
-3. **Inspect/manage the resulting identity-provider record** with `blocks auth idp list [--json]` / `blocks auth idp get <id> [--json]`. Use `blocks auth idp status <id> --active|--active=false` to enable/disable without deleting, and `blocks auth idp delete <id>` to remove it — deleting an identity provider **also deletes its related OIDC client registration**, so treat `idp delete` as the higher-blast-radius operation of the two.
-4. **`blocks auth idp create`/`update` exist as a separate, more general path** for constructing an identity-provider record directly — most relevant when federating an *external* identity provider (Google, Azure AD, Okta, etc.) rather than using Blocks' own OIDC client as the login mechanism:
+   This mirrors exactly what `blocks new web`'s interactive OIDC-client prompt does when scaffolding a new web app. `--register-as-identity-provider` is what turns this from "just an OIDC client" into something the hosted-login redirect flow (`auth.idp.redirectToProvider()` / `auth.idp.callback()`) can authenticate against — per the CLI's own scaffold help text, this registers the client "as a Blocks OIDC identity provider" in the same call.
+3. **Verify the auto-created provider before handing off.** `--register-as-identity-provider` creates the provider record for you — but check what landed in it with `blocks auth idp list --json`, because on the common path several fields come back null. See the footguns below. If `authorizationUrl` is null, hosted login will not redirect: `GET /iam/v4/idp/initiate` (what `auth.idp.redirectToProvider()` calls) builds its target as `provider.AuthorizationUrl ?? ""` plus a query string, so the browser navigates to the app's own origin with OIDC params attached. The repair, for a provider that already exists in that state:
+   ```
+   blocks auth idp update <providerItemId> \
+     --authorization-url "<tenant authorize endpoint>" \
+     --token-url "<tenant token endpoint>" \
+     --user-info-url "<tenant userinfo endpoint>" \
+     [--dry-run] [--yes]
+   ```
+   `idp update` is the only route that persists these three — IAM's create path accepts them in its request model and drops them, and the repository's update is a plain replace with no re-discovery, so values set here stick. **Read the tenant's discovery document for the correct endpoint values rather than composing them by hand** — see the last footgun.
+4. **Inspect/manage the resulting identity-provider record** with `blocks auth idp list [--json]` / `blocks auth idp get <id> [--json]`. Use `blocks auth idp status <id> --active|--active=false` to enable/disable without deleting, and `blocks auth idp delete <id>` to remove it — deleting an identity provider **also deletes its related OIDC client registration**, so treat `idp delete` as the higher-blast-radius operation of the two.
+5. **`blocks auth idp create`/`update` exist as a separate, more general path** for constructing an identity-provider record directly — most relevant when federating an *external* identity provider (Google, Azure AD, Okta, etc.) rather than using Blocks' own OIDC client as the login mechanism:
    ```
    blocks auth idp create --provider <p> --provider-type <t> --protocol <proto> \
      --client-id <id> [--client-secret <secret>] [--display-name] [--issuer] \
      [--scope] [--redirect-uris a,b] [--active] \
-     [--body '<json>'|--file <path>] [--dry-run] [--yes]
+     [--authorization-url] [--token-url] [--user-info-url] [--jwks-uri] \
+     [--well-known-url] [--response-type] [--grant-types a,b] [--require-pkce] \
+     [--token-endpoint-auth-method] [--initial-roles a,b] [--initial-permissions a,b] \
+     [--icon] [--body '<json>'|--file <path>] [--dry-run] [--yes]
    ```
-   `--provider`, `--provider-type`, `--protocol`, and `--client-id` are required on create, and are immutable afterward — `auth idp update <id>` accepts the same flags but IAM requires you to either omit them or echo the existing values exactly. Richer provider configs (JWKS, private keys, initial roles, etc.) go through `--body`/`--file` rather than a dedicated flag. **How exactly a `clientId` passed here pairs with an OIDC client record is not shown anywhere documented** — the two collections are related (per the cascading delete behavior above) but the create/update commands don't expose an explicit "link to this OIDC client" field beyond passing the same id. If you need to federate an external provider, treat `idp create`'s field values as IAM's contract and confirm anything beyond the flags above against the tenant's actual behavior rather than guessing.
-5. **Hand off.** Once a client id (and, if relevant, an identity-provider id) exists, the frontend wiring — login button, callback route, token handling, `client.auth.idp.initiate()`/`redirectToProvider()`/`.callback()` from `@seliseblocks/client` — is owned by **blocks-iam-sso-oidc-implementation**. Do not duplicate that work here; route to it.
+   `--provider`, `--provider-type`, `--protocol`, and `--client-id` are required on create, and are immutable afterward — `auth idp update <id>` accepts the same flags but IAM requires you to either omit them or echo the existing values exactly. Apple-specific fields (`teamId`, `keyId`, `privateKey`, `appleAudience`) go through `--body`/`--file` so no private key lands in shell history. Note that `create` stores `issuer`, `jwksUri` and `wellKnownUrl` but silently drops `authorizationUrl`, `tokenUrl` and `userInfoUrl` — pass those to `idp update` in a second call. **How exactly a `clientId` passed here pairs with an OIDC client record is not shown anywhere documented** — the two collections are related (per the cascading delete behavior above) but the create/update commands don't expose an explicit "link to this OIDC client" field beyond passing the same id. If you need to federate an external provider, treat `idp create`'s field values as IAM's contract and confirm anything beyond the flags above against the tenant's actual behavior rather than guessing.
+6. **Hand off.** Once a client id (and, if relevant, an identity-provider id) exists, the frontend wiring — login button, callback route, token handling, `client.auth.idp.initiate()`/`redirectToProvider()`/`.callback()` from `@seliseblocks/client` — is owned by **blocks-iam-sso-oidc-implementation**. Do not duplicate that work here; route to it.
 
 ## Mutation discipline
 
@@ -56,10 +69,13 @@ Every create/update/delete/status/rotate-secret command above follows the same p
 
 Never raw `fetch`/`curl` these endpoints to route around the CLI's confirmation/dry-run discipline — use the commands above so the same guardrails apply.
 
-## Two verified footguns
+## Verified footguns
 
-- **PKCE lives on the OIDC client only — `auth idp create`/`update` has no PKCE field at all.** `requirePkce` is a real flag on `oidc-clients save` (and `blocks new web`'s scaffold sets it to `true`), but `auth idp create`'s body only reads `clientId`, `clientSecret`, `displayName`, `isActive`, `issuer`, `protocol`, `provider`, `providerType`, `redirectUris`, `scope` — there is no `--require-pkce`/`requirePkce` equivalent on the identity-provider record, and no such flag is documented in `blocks auth idp create --help`. Don't go looking for a matching PKCE setting on the identity provider, and don't assume passing one through `--body`/`--file` does anything — the command doesn't read it.
-- **No `wellKnownUrl` (or equivalent discovery-URL) field is exposed by any `auth idp`/`auth oidc-clients` command in source.** `oidc-clients save` has an `--external-discovery-endpoint` flag (`externalDiscoveryEndpoint` in the request body), but its exact purpose/shape and whether it's tenant-relative or absolute is not explained anywhere in the CLI source or its help text, and `auth idp create`/`update` has no discovery/well-known field whatsoever. **Do not assert a well-known URL shape (e.g. one derived from "the project's own tenant id") as fact — this needs live verification against the tenant API**, not a guess. If a well-known/discovery URL matters for what you're building, treat `--external-discovery-endpoint` as the one lead worth testing live, and confirm the exact shape empirically before documenting it as settled.
+- **`--client-type public` is not cosmetic — omitting it stores a browser app as confidential.** IAM derives `tokenEndpointAuthMethod` from `clientType`: `public` (or any device-flow client) becomes `"none"`, anything else becomes `"client_secret_post"`. Leave `--client-type` off and a PKCE SPA is persisted as a confidential client that is also eligible for the `client_credentials` grant. Always pass `--client-type public` for a browser client. `--require-pkce` alone does not imply it.
+- **The auto-created provider's endpoint URLs come from discovery, and discovery is driven by one field.** IAM's repository-level `CreateIdentityProviderAsync` runs `PopulateProviderEndpointsFromWellKnownAsync` before inserting: if `wellKnownUrl` is set it fetches the document and fills `authorizationUrl`, `tokenUrl`, `userInfoUrl`, `jwksUri` and `issuer` from it. The only input that reaches `wellKnownUrl` on this path is `oidc-clients save --external-discovery-endpoint`. Omit it and the `else` branch runs `GetSocialMetadata(provider)`, which matches only names containing `google` or `microsoft` — for an app-named provider it returns null, so all five fields are written null **and `scope` is overwritten with `"openid profile email"`**, discarding the `offline_access` the OIDC client had just been given. Check both `authorizationUrl` and `scope` on the provider after registering.
+- **This only happens at create.** Re-saving the same OIDC client does not re-run discovery: the `existingProvider` branch never touches `wellKnownUrl`, and the repository's update is a plain replace. A provider already written with null URLs cannot be repaired by re-saving the client — use `idp update`, or delete and recreate.
+- **PKCE and the discovery URL exist on both records and mean different things.** `requirePkce` on the OIDC client governs the app's own authorize flow; `--require-pkce` on `auth idp` governs the *upstream* handshake `/idp/initiate` performs. `--external-discovery-endpoint` on the client is read only as the linked provider's `wellKnownUrl`; on the provider record itself use `--well-known-url`.
+- **Do not compose the tenant's own discovery or authorize URL from a template.** `DiscoveryController` declares `/{tenant_id}/.well-known/openid-configuration` as an absolute route, outside the `/iam/v4` prefix that every other IAM endpoint sits behind, and every `wellKnownUrl` example in IAM's own source and tests is an *external* provider (`accounts.google.com`, `login.microsoftonline.com`, `idp.example.com`) — there is no in-repo example of a Blocks tenant pointing at itself. Whether that route resolves through the `blocksapi.<domain>` gateway as-is or needs an extra segment is **not settled in source**. Fetch the tenant's discovery document and read the endpoints out of it, or ask the user; do not assert a shape you have not seen respond.
 
 ## Secondary, optional: the SDK's `identityProviders` admin methods
 

package/dist/skills/blocks-onboarding/SKILL.md

@@ -65,8 +65,8 @@ Run `blocks init` once per project directory to create `blocks.json`, `blocks/da
 
 Then route to what the user actually wants:
 - Building a frontend from scratch → resolve the app's public OIDC client first, then scaffold:
-  - `blocks auth oidc-clients list --json` — check whether a client already registered for this project fits. If none fits, create one directly (no portal visit needed): `blocks auth oidc-clients save --client-display-name <appName> --redirect-uris https://<domain>:5173/login/callback --scope "openid profile" --require-pkce --register-as-identity-provider --dry-run --json`, then re-run with `--yes` after showing the dry-run output and getting approval. See the blocks-iam-sso-oidc-configuration skill for the full decision tree and field-level gotchas.
-  - `blocks new web <name> --x-blocks-key <tenantId> --app-domain <domain> --client-id <the-resolved-client-id>`. **Always pass `--client-id` and `--app-domain` explicitly** — omitting either drops `new web` into an interactive pick-list prompt with no non-interactive escape (not even to "skip"), which hangs a scripted/agent run with no stdin to answer it. Omit `--blocks-api-url` unless the project uses a non-default gateway; the scaffold derives it from the app domain, e.g. `https://dqrsf.slsblx.com` -> `https://blocksapi.slsblx.com`.
+  - `blocks auth oidc-clients list --json` — check whether a client already registered for this project fits. If none fits, create one directly (no portal visit needed): `blocks auth oidc-clients save --client-display-name <appName> --client-type public --redirect-uris https://<domain>:5173/login/callback --scope "openid profile" --require-pkce --register-as-identity-provider --dry-run --json`, then re-run with `--yes` after showing the dry-run output and getting approval. `--client-type public` is required — IAM derives `tokenEndpointAuthMethod` from it, so omitting it stores a browser client as confidential. `--register-as-identity-provider` creates the linked identity provider in the same call; nothing further to run. See the blocks-iam-sso-oidc-configuration skill for the full decision tree and field-level gotchas.
+  - `blocks new web <name> --x-blocks-key <tenantId> --app-domain <domain> --client-id <the-resolved-client-id>`. **Always pass `--client-id` and `--app-domain` explicitly** — omitting either drops `new web` into an interactive pick-list prompt with no non-interactive escape (not even to "skip"), which hangs a scripted/agent run with no stdin to answer it. Omit `--blocks-api-url` unless the project uses a non-default gateway; the scaffold derives it from the app domain, e.g. `https://dqrsf.slsblx.com` -> `https://blocksapi.slsblx.com`.
 - Defining data / CRUD / localization / release on an existing project → hand off to the matching skill; the project is already selected via `blocks use`, so its commands can proceed directly.
 
 ## Gotchas