@seliseblocks/cli-os 0.2.11 → 0.2.12

package/dist/skills/blocks-data-gateway-crud/SKILL.md

@@ -1,223 +0,0 @@
----
-name: blocks-data-gateway-crud
-description: "Implement create/read/update/delete against a SELISE Blocks project's runtime Data Gateway using the @seliseblocks/client SDK. Use data.collection(schemaName) for straightforward per-item CRUD, data.graphql() for joins or custom query shapes, and data.schemas.*/data.validations.* for schema/validation metadata. Shows how to wire CRUD into the React 18 + Vite + TanStack Query app that blocks new web scaffolds. Use whenever the user wants to read or write actual records through a Blocks Data schema from app code."
----
-
-# Blocks Data - Gateway CRUD
-
-Once a schema exists and has been reloaded via the blocks-data-gateway-configuration skill, the Data Gateway exposes runtime records through GraphQL. This skill shows how to use the generated app's shared `@seliseblocks/client` instance for CRUD. Do not use raw `fetch` or `curl` against Blocks APIs from app code.
-
-Prerequisite: a project selected via `blocks use` and an app scaffolded with `blocks new web <name> ...`. If either is missing, run the blocks-onboarding skill first.
-
-## Use the Existing Client
-
-The scaffold creates one `createBlocksClient()` call in `src/lib/blocks/client.ts`:
-
-```ts
-import { createBlocksClient } from "@seliseblocks/client";
-import { blocksConfig } from "./config";
-import { getValidAccessToken } from "./auth";
-
-export const blocksClient = createBlocksClient({
-  accessToken: () => getValidAccessToken(),
-  apiUrl: blocksConfig.apiUrl,
-  appDomain: blocksConfig.appDomain,
-  oidc: { clientId: blocksConfig.oidcClientId, scope: blocksConfig.oidcScope, url: blocksConfig.oidcUrl },
-  xBlocksKey: blocksConfig.xBlocksKey
-});
-```
-
-Import that existing instance from feature code. Do not create a second client.
-
-- `xBlocksKey` is the project's public tenant key from `VITE_BLOCKS_X_BLOCKS_KEY`.
-- The SDK does not add `ProjectKey` to runtime Data calls.
-- The HTTP client sends `credentials: "include"` so hosted-login session cookies are included.
-- Never use the CLI's impersonation token or project token in browser code.
-
-## Preferred CRUD Helper
-
-Use `blocksClient.data.collection<T>(schemaName, options)` for normal CRUD. Pass the schema name, not the collection name. For a schema named `Product` with collection `Products`, pass `"Product"`.
-
-```ts
-const products = blocksClient.data.collection<Product>("Product", {
-  fields: ["name", "price", "status"]
-});
-
-products.list({ pageNo: 1, pageSize: 20 });
-products.get(itemId);
-products.create(payload);
-products.update(itemId, payload);
-products.delete(itemId);
-```
-
-What the helper does:
-
-- `list` and `get` call `query getProducts($input: DynamicQueryInput)`.
-- `create` calls `mutation insertProduct($input: ProductInsertInput!)`.
-- `update` calls `mutation updateProduct($filter: String, $input: ProductUpdateInput!)`.
-- `delete` calls `mutation deleteProduct($filter: String, $input: ProductDeleteInput!)`.
-- `get`, `update`, and `delete` address records by `ItemId`.
-- `fields` controls the GraphQL selection for returned items; `ItemId` is always selected.
-
-`list` accepts paging plus optional GraphQL dynamic input values:
-
-```ts
-await products.list({
-  pageNo: 1,
-  pageSize: 20,
-  filter: { status: "Active" },
-  sort: { name: 1 }
-});
-```
-
-For search, only send filters that the schema/runtime actually supports. If unsure, start with simple paging and client-side filtering, or inspect the schema first.
-
-## Product Example
-
-```ts
-// src/features/products/productsApi.ts
-import { blocksClient } from "../../lib/blocks/client";
-
-export type Product = Record<string, unknown> & {
-  itemId?: string;
-  id?: string;
-  name?: string;
-  price?: number;
-  status?: string;
-};
-
-export type ProductInput = { name: string; price: number; status: string };
-
-const products = blocksClient.data.collection<Product>("Product", {
-  fields: ["name", "price", "status"]
-});
-
-export async function listProducts({ page, pageSize }: { page: number; pageSize: number }) {
-  const response = await products.list({ pageNo: page, pageSize });
-  return normalizeProductList(response);
-}
-
-export function createProduct(input: ProductInput) {
-  return products.create(input);
-}
-
-export function updateProduct(product: Product) {
-  return products.update(productId(product), product);
-}
-
-export function deleteProduct(product: Product) {
-  return products.delete(productId(product));
-}
-
-function productId(product: Product): string {
-  const id = product.itemId ?? product.id;
-  if (!id) throw new Error("Product item id is missing.");
-  return String(id);
-}
-
-function normalizeProductList(response: unknown): { items: Product[]; totalCount: number } {
-  const record = response as {
-    data?: {
-      getProducts?: { items?: Product[]; totalCount?: number };
-      items?: Product[];
-      totalCount?: number;
-    };
-    items?: Product[];
-    totalCount?: number;
-  };
-  const gateway = record.data?.getProducts;
-  const items = gateway?.items ?? record.data?.items ?? record.items ?? [];
-  return { items, totalCount: gateway?.totalCount ?? record.data?.totalCount ?? record.totalCount ?? items.length };
-}
-```
-
-```ts
-// src/features/products/useProducts.ts
-import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import { createProduct, deleteProduct, listProducts, updateProduct } from "./productsApi";
-import type { Product, ProductInput } from "./productsApi";
-
-export function useProductsQuery(page: number, pageSize: number) {
-  return useQuery({
-    queryKey: ["products", page, pageSize],
-    queryFn: () => listProducts({ page, pageSize })
-  });
-}
-
-export function useProductMutations() {
-  const queryClient = useQueryClient();
-  const invalidate = () => queryClient.invalidateQueries({ queryKey: ["products"] });
-
-  return {
-    create: useMutation({ mutationFn: (input: ProductInput) => createProduct(input), onSuccess: invalidate }),
-    update: useMutation({ mutationFn: (product: Product) => updateProduct(product), onSuccess: invalidate }),
-    remove: useMutation({ mutationFn: (product: Product) => deleteProduct(product), onSuccess: invalidate })
-  };
-}
-```
-
-## When to Use `data.graphql()`
-
-Use `data.graphql({ query, variables, operationName })` when the collection helper is too small:
-
-- joins across schemas;
-- custom nested selections;
-- generated `where`, `order`, or `paging` arguments;
-- bulk operations such as `insertManyProduct`.
-
-Example:
-
-```ts
-const result = await blocksClient.data.graphql({
-  operationName: "getProducts",
-  query: `
-    query getProducts($input: DynamicQueryInput) {
-      getProducts(input: $input) {
-        items { ItemId name price status }
-        totalCount
-      }
-    }
-  `,
-  variables: { input: { pageNo: 1, pageSize: 20 } }
-});
-```
-
-## Schema Metadata
-
-Use `data.schemas.*` when building dynamic UI:
-
-- `data.schemas.list(options)` or `data.schemas.get(schemaName)` for discovery;
-- `data.schemas.infoByName(schemaName)` for field-level metadata;
-- `data.schemas.info()` for general schema info;
-- `data.schemas.aggregation(options)` for summary views;
-- `data.schemas.getById(id)` when you already have the schema id.
-
-Use `data.validations.*` to read field-level validation rules at runtime (e.g. to drive client-side form validation from the same rules the backend enforces):
-
-- `data.validations.list(options)` for all rules, with optional schema/field/paging filters;
-- `data.validations.bySchemaId(schemaId)` for every rule on one schema;
-- `data.validations.bySchemaAndField({ schemaId, fieldName })` for one field's rule;
-- `data.validations.getById(id)` when you already have the validation id.
-
-Validation rules are authored and saved separately via `blocks data validation save` (see the blocks-data-gateway-configuration skill); this SDK namespace only reads them.
-
-## Gotchas
-
-- Pass schema name, not collection name: `Product`, not `Products`.
-- Generated query names pluralize by naive concatenation -- literally appending `s`, not English pluralization: `getProducts`, but `Company` -> `getCompanys`, not `getCompanies`. Never guess a pluralized name; read it from the schema's `querySchema` field (via `data.schemas.get`/`getByName` or `blocks data schema get <id>`) and use `get${querySchema}`.
-- Generated mutation names stay singular: `insertProduct`, `updateProduct`, `deleteProduct`. Bulk variants follow the same pattern but are not listed in `mutationSchemas`: `insertManyProduct`, `updateManyProduct`, `deleteManyProduct`.
-- Dynamic item selections use schema field names such as `ItemId`, `name`, `price`.
-- Mutation response fields are lower camel case: `acknowledged`, `itemId`, `message`, `totalImpactedData`.
-- If GraphQL says the field does not exist, the schema probably has not been created or reloaded.
-- Keep one `blocksClient` per app.
-
-## Prompt Routing
-
-```text
-Wire create/read/update/delete for Product into my React app          -> this skill
-Build a paged table of Orders in the dashboard                       -> this skill
-I need a GraphQL query that joins Orders with Customer details        -> this skill, data.graphql
-Build a dynamic form from my schema's field metadata                  -> this skill, data.schemas.infoByName
-Create a Product schema with title/price and reload it                -> blocks-data-gateway-configuration
-Upload a PDF and get a download link                                  -> blocks-data-storage
-```

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

@@ -1,253 +0,0 @@
----
-name: blocks-data-storage
-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
-
-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.
-
-Use:
-
-- **`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`.
-
-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.
-
-Store the returned `fileId` in a Data record when attaching a file to domain data. Use blocks-data-gateway-crud for the record mutation.
-
-## Choose the surface
-
-The current CLI and SDK follow the backend's file, directory, and object resource groups.
-
-```bash
-blocks --version
-blocks data files --help
-```
-
-- 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.
-
-Legacy `data.dms.*`, `dms-upload`, `dms-list`, `create-folder`, and `delete-folder` wrappers are retired. Uploads need no registration call.
-
-## Upload a new file
-
-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.
-
-### Cloud upload from the CLI
-
-Prefer the composed command. It previews and confirms both metadata creation and the provider PUT:
-
-```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
-```
-
-Use the two explicit commands only when the intermediate upload URL is required:
-
-```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
-```
-
-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.
-
-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.
-
-### Cloud upload from app code
-
-```ts
-const presign = await blocksClient.data.files.presignedUploadUrl({
-  name: "invoice.pdf",
-  parentDirectoryId: directoryId,
-  configurationName: "Default",
-  accessModifier: "Private",
-  tags: "invoice,2026",
-});
-
-if (!presign || typeof presign !== "object") {
-  throw new Error("Unexpected upload response");
-}
-
-const result = presign as {
-  uploadUrl: string;
-  fileId: string;
-  isSuccess: boolean;
-  errors?: Record<string, string>;
-};
-
-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",
-});
-```
-
-`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.
-
-### Local-storage upload
-
-```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
-const uploaded = await blocksClient.data.files.uploadToLocalStorage({
-  name: file.name,
-  file,
-  parentDirectoryId: directoryId,
-  configurationName: "Default",
-  accessModifier: "Private",
-  tags: ["invoice", "2026"],
-});
-```
-
-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
-
-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:
-
-```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
-const history = await blocksClient.data.files.versions({ fileId, limit: 25 });
-const next = await blocksClient.data.files.createVersion({ fileId, configurationName: "Default" });
-```
-
-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.
-
-## 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 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
-```
-
-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.
-
-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.
-
-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
-
-- 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

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