@docyrus/docyrus 0.0.31 → 0.0.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docyrus/docyrus",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "private": false,
   "description": "Docyrus API CLI",
   "main": "./main.js",

package/resources/pi-agent/extensions/docyrus-web-browser.ts

@@ -0,0 +1,31 @@
+import { isToolCallEventType, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { buildDocyrusWebBrowserProtocolInstructions } from "../shared/docyrusWebBrowserProtocol";
+
+const DOCYRUS_CHROME_COMMAND_PATTERN = /\bdocyrus\b(?:\s+-g|\s+--global)?\s+chrome\b/;
+const DOCYRUS_CHROME_BLOCK_REASON =
+  "Docyrus Server sessions must use the docyrus-web-browser preview tools instead of `docyrus chrome`.";
+
+export default function docyrusWebBrowserExtension(pi: ExtensionAPI) {
+  pi.on("before_agent_start", async(event) => {
+    const protocolInstructions = buildDocyrusWebBrowserProtocolInstructions();
+    return {
+      systemPrompt: [event.systemPrompt, protocolInstructions].filter(Boolean).join("\n\n"),
+    };
+  });
+
+  pi.on("tool_call", async(event) => {
+    if (!isToolCallEventType("bash", event)) {
+      return;
+    }
+
+    const command = typeof event.input.command === "string" ? event.input.command.trim() : "";
+    if (!command || !DOCYRUS_CHROME_COMMAND_PATTERN.test(command)) {
+      return;
+    }
+
+    return {
+      block: true,
+      reason: DOCYRUS_CHROME_BLOCK_REASON,
+    };
+  });
+}

package/resources/pi-agent/shared/docyrusWebBrowserProtocol.ts

@@ -0,0 +1,169 @@
+export const DOCYRUS_WEB_BROWSER_EXTENSION_NAME = "docyrus-web-browser";
+export const DOCYRUS_WEB_BROWSER_TAG = "docyrus_web_browser";
+export const DOCYRUS_WEB_BROWSER_OPEN = `<${DOCYRUS_WEB_BROWSER_TAG}>`;
+export const DOCYRUS_WEB_BROWSER_CLOSE = `</${DOCYRUS_WEB_BROWSER_TAG}>`;
+export const DOCYRUS_WEB_BROWSER_RESULT_TAG = "docyrus_web_browser_result";
+export const DOCYRUS_WEB_BROWSER_RESULT_OPEN = `<${DOCYRUS_WEB_BROWSER_RESULT_TAG}>`;
+export const DOCYRUS_WEB_BROWSER_RESULT_CLOSE = `</${DOCYRUS_WEB_BROWSER_RESULT_TAG}>`;
+export const WEB_PREVIEW_CONTEXT_TOOL = "web_preview_context";
+export const WEB_PREVIEW_PLAYWRIGHT_TOOL = "web_preview_playwright";
+
+export const DOCYRUS_WEB_BROWSER_TOOL_NAMES = [
+  WEB_PREVIEW_CONTEXT_TOOL,
+  WEB_PREVIEW_PLAYWRIGHT_TOOL,
+] as const;
+
+export type IDocyrusWebBrowserToolName = typeof DOCYRUS_WEB_BROWSER_TOOL_NAMES[number];
+
+export interface IDocyrusWebBrowserToolRequest {
+  tool: IDocyrusWebBrowserToolName;
+  input?: Record<string, unknown>;
+}
+
+export interface IDocyrusWebBrowserToolResponsePrompt {
+  tool: IDocyrusWebBrowserToolName;
+  request?: Record<string, unknown>;
+  status: "success" | "error";
+  output?: unknown;
+  errorText?: string;
+}
+
+export interface IDocyrusWebBrowserClientToolInfo {
+  name: IDocyrusWebBrowserToolName;
+  description: string;
+  inputSchema?: Record<string, unknown>;
+}
+
+export const DOCYRUS_WEB_BROWSER_CLIENT_TOOLS: IDocyrusWebBrowserClientToolInfo[] = [
+  {
+    name: WEB_PREVIEW_CONTEXT_TOOL,
+    description:
+      "Inspect the current Docyrus web preview state before automation. Prefer this first when preview availability or bridge state is unknown.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        includeSnapshot: { type: "boolean" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: WEB_PREVIEW_PLAYWRIGHT_TOOL,
+    description:
+      "Run Playwright-style actions against the Docyrus web preview. Prefer structured steps over raw scripts.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        script: { type: "string" },
+        steps: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              action: { type: "string" },
+              selector: { type: "string" },
+              url: { type: "string" },
+              value: { type: "string" },
+              values: {
+                type: "array",
+                items: { type: "string" },
+              },
+              key: { type: "string" },
+              attribute: { type: "string" },
+              timeoutMs: { type: "number" },
+              state: { type: "string" },
+            },
+            additionalProperties: true,
+          },
+        },
+        timeoutMs: { type: "number" },
+        stopOnError: { type: "boolean" },
+      },
+      additionalProperties: true,
+    },
+  },
+];
+
+function hashString(value: string): string {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = ((hash << 5) - hash) + value.charCodeAt(index);
+    hash |= 0;
+  }
+  return Math.abs(hash).toString(36);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function isDocyrusWebBrowserToolName(value: unknown): value is IDocyrusWebBrowserToolName {
+  return DOCYRUS_WEB_BROWSER_TOOL_NAMES.some((toolName) => toolName === value);
+}
+
+export function normalizeDocyrusWebBrowserToolRequest(value: unknown): IDocyrusWebBrowserToolRequest | undefined {
+  if (!isRecord(value) || !isDocyrusWebBrowserToolName(value.tool)) {
+    return undefined;
+  }
+
+  return {
+    tool: value.tool,
+    input: isRecord(value.input) ? value.input : undefined,
+  };
+}
+
+export function serializeDocyrusWebBrowserToolRequest(request: IDocyrusWebBrowserToolRequest): string {
+  return `${DOCYRUS_WEB_BROWSER_OPEN}\n${JSON.stringify(request, null, 2)}\n${DOCYRUS_WEB_BROWSER_CLOSE}`;
+}
+
+export function createDocyrusWebBrowserToolCallId(request: IDocyrusWebBrowserToolRequest): string {
+  return `docyrus_web_browser_${hashString(JSON.stringify(request))}`;
+}
+
+export function parseDocyrusWebBrowserRequestFromText(text: string): IDocyrusWebBrowserToolRequest | undefined {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith(DOCYRUS_WEB_BROWSER_OPEN) || !trimmed.endsWith(DOCYRUS_WEB_BROWSER_CLOSE)) {
+    return undefined;
+  }
+
+  const body = trimmed.slice(DOCYRUS_WEB_BROWSER_OPEN.length, trimmed.length - DOCYRUS_WEB_BROWSER_CLOSE.length).trim();
+  if (!body) {
+    return undefined;
+  }
+
+  try {
+    return normalizeDocyrusWebBrowserToolRequest(JSON.parse(body));
+  } catch {
+    return undefined;
+  }
+}
+
+export function buildDocyrusWebBrowserProtocolInstructions(): string {
+  return [
+    "When you need to inspect or automate the Docyrus web preview in server-backed sessions, use the docyrus-web-browser client tools.",
+    "Do not use `docyrus chrome` or any visible Chrome DevTools workflow in this environment.",
+    `Instead, output only a single ${DOCYRUS_WEB_BROWSER_OPEN}...${DOCYRUS_WEB_BROWSER_CLOSE} block and nothing else in the assistant message.`,
+    "Inside that block, emit strict JSON with this shape:",
+    "{\"tool\":\"web_preview_context\",\"input\":{\"includeSnapshot\":true}}",
+    "or",
+    "{\"tool\":\"web_preview_playwright\",\"input\":{\"steps\":[{\"action\":\"goto\",\"url\":\"/login\"},{\"action\":\"fill\",\"selector\":\"input[name='email']\",\"value\":\"demo@example.com\"}],\"timeoutMs\":10000,\"stopOnError\":true}}",
+    "Call `web_preview_context` first when preview state is unknown.",
+    "Prefer `steps` over `script` for `web_preview_playwright`.",
+    "Supported playwright step actions are: goto, click, dblclick, hover, fill, press, select, check, uncheck, waitForSelector, waitForTimeout, textContent, getAttribute, title, url, snapshot.",
+    "If the tool reports that the preview is unavailable or blocked by bridge/cross-origin constraints, stop and explain the exact blocker to the user.",
+  ].join("\n");
+}
+
+export function formatDocyrusWebBrowserToolResponsePrompt(
+  response: IDocyrusWebBrowserToolResponsePrompt,
+): string {
+  return [
+    "The docyrus-web-browser client tool returned a result.",
+    "",
+    `${DOCYRUS_WEB_BROWSER_RESULT_OPEN}`,
+    JSON.stringify(response, null, 2),
+    `${DOCYRUS_WEB_BROWSER_RESULT_CLOSE}`,
+    "",
+    "Continue the task using this result. If the tool reported an availability or bridge blocker, explain that blocker exactly and do not claim success.",
+  ].join("\n");
+}

package/resources/pi-agent/skills/diffity-diff/SKILL.md

@@ -14,7 +14,7 @@ You are opening the diffity diff viewer so the user can see their changes in the
 
 ## Instructions
 
-1. Check that `diffity` is available: run `which diffity`. If not found, tell the user to restart `docyrus coder` so the launcher can install the managed `diffity` CLI.
+1. Check that `diffity` is available: run `which diffity`. If not found, install it with `npm install -g diffity`.
 2. Run `diffity <ref>` (or just `diffity` if no ref) using the Bash tool with `run_in_background: true`:
    - The CLI handles everything: if an instance is already running for this repo it reuses it and opens the browser, otherwise it starts a new server and opens the browser.
    - Do NOT use `&` or `--quiet` — let the Bash tool handle backgrounding.

package/resources/pi-agent/skills/diffity-resolve/SKILL.md

@@ -15,6 +15,7 @@ You are reading open review comments and resolving them by making the requested
 ## CLI Reference
 
 ```
+diffity agent diff
 diffity agent list [--status open|resolved|dismissed] [--json]
 diffity agent comment --file <path> --line <n> [--end-line <n>] [--side new|old] --body "<text>"
 diffity agent general-comment --body "<text>"
@@ -31,7 +32,7 @@ diffity agent reply <id> --body "<text>"
 
 ## Prerequisites
 
-1. Check that `diffity` is available: run `which diffity`. If not found, tell the user to restart `docyrus coder` so the launcher can install the managed `diffity` CLI.
+1. Check that `diffity` is available: run `which diffity`. If not found, install it with `npm install -g diffity`.
 2. Check that a review session exists: run `diffity agent list`. If this fails with "No active review session", tell the user to start diffity first (e.g. `diffity` or **/diffity-diff**).
 
 ## Instructions
@@ -46,11 +47,10 @@ diffity agent reply <id> --body "<text>"
    a. **Skip** general comments (filePath `__general__`) — these are summaries, not actionable code changes.
    b. **Skip** threads where the last comment is an agent reply that asks the user a question (e.g. "Could you clarify...?") and the user hasn't responded yet — the agent is waiting for user input. Still process threads where the agent left the original comment (code suggestion, review feedback, etc.) — those are actionable.
    c. **`[nit]` comments** — these are minor suggestions but still actionable. Resolve them like any other comment.
-   d. **`[question]` comments** (from the user) — read the question, examine the relevant code, and reply with an answer:
+   d. **`[question]` comments** (from the user) — read the question, examine the relevant code, and resolve the thread with your answer as the summary:
       ```
-      diffity agent reply <thread-id> --body "Your answer here"
+      diffity agent resolve <thread-id> --summary "Your answer here"
       ```
-      Then resolve the thread with a summary of your answer.
    e. Comments phrased as questions without an explicit `[question]` tag (e.g. "should we add X?" or "can we rename this?") are suggestions — treat them as actionable requests and make the change.
    f. Read the comment body from the JSON output and understand what change is requested. Interpret the intent:
       - If the comment suggests a code change, make the change.

package/resources/pi-agent/skills/diffity-review/SKILL.md

@@ -16,6 +16,7 @@ You are reviewing a diff and leaving inline comments using the `diffity agent` C
 ## CLI Reference
 
 ```
+diffity agent diff
 diffity agent list [--status open|resolved|dismissed] [--json]
 diffity agent comment --file <path> --line <n> [--end-line <n>] [--side new|old] --body "<text>"
 diffity agent general-comment --body "<text>"
@@ -32,7 +33,7 @@ diffity agent reply <id> --body "<text>"
 
 ## Prerequisites
 
-1. Check that `diffity` is available: run `which diffity`. If not found, tell the user to restart `docyrus coder` so the launcher can install the managed `diffity` CLI.
+1. Check that `diffity` is available: run `which diffity`. If not found, install it with `npm install -g diffity`.
 
 ## Instructions
 
@@ -53,11 +54,11 @@ The review needs a running session whose ref matches the requested ref. A ref mi
 
 ### Step 2: Review the diff
 
-1. **Get the resolved diff args from diffity's API**, then run `git diff` yourself — do NOT construct the diff ref manually, as diffity uses merge-base resolution:
+1. **Get the unified diff** directly from diffity — this handles merge-base resolution, untracked files, and all ref types automatically:
    ```
-   curl -s 'http://localhost:<port>/api/diff/ref?ref=<ref>'
+   diffity agent diff
    ```
-   If no ref was provided, omit the `ref` query parameter. The response is JSON with an `args` field (e.g. `"abc123def"`). Run `git diff <args>` to get the unified diff. Line numbers are in the `@@` hunk headers.
+   This outputs the full unified diff for the current session. Line numbers are in the `@@` hunk headers.
 2. Find and read all relevant CLAUDE.md files — the root CLAUDE.md and any CLAUDE.md files in directories containing modified files. These define project-specific rules that the diff must follow.
 
 #### Understand the change before reviewing it

package/resources/pi-agent/skills/docyrus-api-dev/SKILL.md

@@ -89,6 +89,36 @@ GET    /v1/users/me       — Current user profile
 PATCH  /v1/users/me       — Update current user
 ```
 
+### ACL / Role Management Endpoints
+```
+GET    /v1/users/acl?dataSourceId={uuid}&recordId={uuid}   — Read record ACL rows
+POST   /v1/users/acl/share                                 — Upsert record shares
+DELETE /v1/users/acl/share                                 — Revoke record shares
+PUT    /v1/users/acl/owner                                 — Transfer record ownership
+
+GET    /v1/users/acl/roles                                 — List roles
+GET    /v1/users/acl/roles/{roleId}                        — Get one role
+POST   /v1/users/acl/roles                                 — Create role
+PATCH  /v1/users/acl/roles/{roleId}                        — Update role
+DELETE /v1/users/acl/roles/{roleId}                        — Delete role
+
+GET    /v1/users/acl/user-roles                            — List user-role assignments
+GET    /v1/users/acl/users/{userId}/roles                  — List one user's roles
+POST   /v1/users/acl/users/{userId}/roles                  — Add roles to a user
+PUT    /v1/users/acl/users/{userId}/roles                  — Replace a user's full role set
+DELETE /v1/users/acl/users/{userId}/roles/{roleId}         — Remove one role assignment
+
+GET    /v1/users/acl/role-queries                          — List role queries
+GET    /v1/users/acl/role-queries/{roleQueryId}            — Get one role query
+POST   /v1/users/acl/role-queries                          — Create role query
+PATCH  /v1/users/acl/role-queries/{roleQueryId}            — Update role query
+DELETE /v1/users/acl/role-queries/{roleQueryId}            — Delete role query
+```
+
+ACL routes require the normal authenticated API session, but they may not appear in generated Swagger/OpenAPI output because the backend currently excludes them from public docs. Integrate them with direct `RestApiClient` calls when you need record sharing, role CRUD, user-role assignment management, or role-query management.
+
+For all ACL role operations, prefer using role `uid` values returned by the API. Nested role objects expose both `id` and `uid`, and both map to the role UID value.
+
 ### Making API Calls
 
 ```typescript
@@ -150,6 +180,11 @@ The GET items endpoint accepts a powerful query payload:
 4. **Child query keys must appear in `columns`** — if childQuery key is `orders`, include `orders` in columns.
 5. **Formula keys must appear in `columns`** — if formula key is `total`, include `total` in columns.
 6. **Filter by related field** using `rel_{{relation_field}}/{{field}}` syntax.
+7. **ACL routes may be hidden from generated OpenAPI** — call them directly via `RestApiClient` instead of expecting generated collection support.
+8. **Prefer role `uid` values** for ACL role writes, user-role `roleIds`, and role-query `roleIds`.
+9. **Treat `PUT /v1/users/acl/users/:userId/roles` as full replacement** and `POST /v1/users/acl/users/:userId/roles` as additive.
+10. **Send role-query `query` as raw JSON** and let backend derive `tenantAppId` from `dataSourceId` when applicable.
+11. **After deleting a role, refresh dependent ACL state** — role lists, user-role lists, role-query lists, and any UI showing primary-role labels.
 
 ## References
 
@@ -159,3 +194,4 @@ Read these files when you need detailed information:
 - **`references/authentication.md`** — @docyrus/signin React provider, useDocyrusAuth/useDocyrusClient hooks, hasRole/hasPermission authorization helpers, SignInButton, standalone vs iframe auth modes, env vars, API client access pattern
 - **`references/data-source-query-guide.md`** — Up-to-date query payload guide: columns, filters, orderBy, pagination, calculations, formulas, child queries, pivots, and operator reference
 - **`references/formula-design-guide-llm.md`** — Up-to-date formula design guide for building and validating `formulas` payloads
+- **`references/acl-endpoints-frontend.md`** — Hidden ACL endpoint reference covering record sharing, roles, user-role assignment flows, role queries, identifier rules, and expected frontend integration behavior

package/resources/pi-agent/skills/docyrus-api-dev/references/acl-endpoints-frontend.md

@@ -0,0 +1,295 @@
+# ACL Endpoints for Frontend Developers
+
+Base path: `/api/v1/users/acl`
+
+All ACL endpoints require the normal authenticated API session.
+
+These endpoints may be hidden from generated Swagger/OpenAPI output because the backend currently marks them with `@ApiExcludeEndpoint()`. Treat this document as the frontend integration source of truth and call these routes directly with `RestApiClient` or `useDocyrusClient()`.
+
+## Important identifier rules
+
+- Role assignments and ACL role relations are stored using `tenant_role.uid`.
+- Returned nested role objects expose both `id` and `uid`, and both values map to the role UID.
+- For role operations, backend can resolve incoming `roleId` values against both `tenant_role.uid` and `tenant_role.id`, but frontend apps should prefer role `uid` values from API responses.
+- For user-role writes and role-query `roleIds`, send role UUIDs and prefer UID values.
+- `tenant_role_query.query` is a JSON object matching the app's filter-query structure. Send raw JSON, not stringified JSON.
+
+## Enum values
+
+### Role ownership
+
+- `APP`
+- `CUSTOM`
+- `PRODUCT`
+- `SYSTEM`
+- `USER`
+
+### Role query restriction level
+
+- `hidden`
+- `read-only`
+- `not-deletable`
+
+## Endpoint groups
+
+### 1) Record ACL endpoints
+
+These manage record-level shares, not role CRUD.
+
+| Method | Path | Purpose |
+| :----- | :--- | :------ |
+| `GET` | `/v1/users/acl?dataSourceId={uuid}&recordId={uuid}` | Fetch direct and effective ACL rows for a record |
+| `POST` | `/v1/users/acl/share` | Upsert record share rows |
+| `DELETE` | `/v1/users/acl/share` | Revoke matching share rows |
+| `PUT` | `/v1/users/acl/owner` | Transfer record ownership |
+
+#### Share payload notes
+
+- `principalType` must be one of: `user`, `team`, `role`, `tenant`, `public`.
+- `permissions` is the backend ACL bitmask value.
+- `expiresAt` is optional and must be a valid ISO date if provided.
+
+#### Record ACL response shapes
+
+`GET /v1/users/acl` returns:
+
+```json
+{
+  "direct": [
+    {
+      "id": "uuid",
+      "principal_type": "user",
+      "principal_id": "uuid",
+      "permissions": 7,
+      "expires_at": null,
+      "created_by": "uuid-or-null",
+      "created_on": "2026-03-29T20:10:00.000Z"
+    }
+  ],
+  "effective": [
+    {
+      "id": "uuid",
+      "user_id": "uuid",
+      "permissions": 7,
+      "source_principal_type": "role",
+      "source_principal_id": "uuid"
+    }
+  ]
+}
+```
+
+### 2) Role endpoints
+
+| Method | Path | Purpose |
+| :----- | :--- | :------ |
+| `GET` | `/v1/users/acl/roles` | List tenant roles |
+| `GET` | `/v1/users/acl/roles/:roleId` | Get one role |
+| `POST` | `/v1/users/acl/roles` | Create role |
+| `PATCH` | `/v1/users/acl/roles/:roleId` | Partial update role |
+| `DELETE` | `/v1/users/acl/roles/:roleId` | Hard delete role |
+
+#### Role create/update rules
+
+- `slug` is required on create and must be unique within the tenant.
+- Create defaults:
+  - `ownership = "CUSTOM"`
+  - `privileges = ""`
+  - `status = 1`
+- Role responses include both `id` and `uid`, both pointing to the role UID.
+
+#### Role delete side effects
+
+Deleting a role also cleans up dependent ACL state:
+
+- removes `tenant_user_role` assignments for that role
+- sets `tenant_user.primary_role` to `null` where applicable
+- removes linked `tenant_acl_rule` rows
+- removes linked `tenant_acl_field_rule` rows
+- removes the role from `tenant_role_query` role arrays
+- hard deletes role-query rows that become empty after role removal
+
+Frontend implication: after role deletion, refresh role lists, user-role lists, role-query lists, and any UI showing primary-role labels.
+
+### 3) User-role endpoints
+
+| Method | Path | Purpose |
+| :----- | :--- | :------ |
+| `GET` | `/v1/users/acl/user-roles` | List assignments across the tenant |
+| `GET` | `/v1/users/acl/users/:userId/roles` | List assignments for one user |
+| `POST` | `/v1/users/acl/users/:userId/roles` | Add roles to a user |
+| `PUT` | `/v1/users/acl/users/:userId/roles` | Replace the full role set for a user |
+| `DELETE` | `/v1/users/acl/users/:userId/roles/:roleId` | Remove one role assignment |
+
+#### User-role behavior
+
+- `GET /v1/users/acl/user-roles` accepts optional `userId` and `roleId` filters.
+- If `roleId` is supplied, backend resolves it to the canonical role UID first.
+- `POST /users/:userId/roles` is additive.
+- `POST /users/:userId/roles` safely ignores duplicate assignments.
+- `PUT /users/:userId/roles` is a full replacement operation.
+- Sending `roleIds: []` to `PUT /users/:userId/roles` clears all additional roles for that user.
+
+### 4) Role-query endpoints
+
+Role queries are role-based filtering rules attached to roles and optionally scoped to a specific data source.
+
+| Method | Path | Purpose |
+| :----- | :--- | :------ |
+| `GET` | `/v1/users/acl/role-queries` | List role queries |
+| `GET` | `/v1/users/acl/role-queries/:roleQueryId` | Get one role query |
+| `POST` | `/v1/users/acl/role-queries` | Create role query |
+| `PATCH` | `/v1/users/acl/role-queries/:roleQueryId` | Partial update role query |
+| `DELETE` | `/v1/users/acl/role-queries/:roleQueryId` | Hard delete role query |
+
+#### Role-query rules
+
+- `roleIds` is required on create and must contain at least one UUID.
+- Stored role IDs are normalized to role UIDs.
+- `query` is required on create and must be a JSON object.
+- `filterChildRelations` defaults to `false`.
+- `restrictionLevel` defaults to `hidden`.
+- If `dataSourceId` is provided, backend derives `tenantAppId` automatically.
+- If `dataSourceId` changes during update, backend recalculates `tenantAppId`.
+
+## Common request examples
+
+### Sync a user's complete role set
+
+```json
+{
+  "roleIds": ["role-uid-uuid-1", "role-uid-uuid-2"]
+}
+```
+
+### Create a role query
+
+```json
+{
+  "name": "Hide archived records",
+  "dataSourceId": "data-source-uuid",
+  "roleIds": ["role-uid-uuid"],
+  "query": {
+    "condition": "and",
+    "filters": []
+  },
+  "filterChildRelations": false,
+  "restrictionLevel": "hidden"
+}
+```
+
+### Share a record
+
+```json
+{
+  "dataSourceId": "uuid",
+  "recordId": "uuid",
+  "items": [
+    {
+      "principalType": "user",
+      "principalId": "uuid",
+      "permissions": 7,
+      "expiresAt": "2026-12-31T00:00:00.000Z"
+    }
+  ]
+}
+```
+
+## Error expectations
+
+Common backend error patterns:
+
+- `400 Bad Request`
+  - malformed UUID in path, query, or body
+  - missing required DTO fields
+  - invalid enum values
+  - invalid boolean or date format in share payloads
+- `404 Not Found`
+  - role not found
+  - role query not found
+  - tenant user not found
+  - tenant data source not found
+  - one or more submitted role IDs could not be resolved
+- `409 Conflict`
+  - role slug already exists in the tenant
+- `500 Internal Server Error`
+  - unexpected persistence failure
+
+## Frontend integration recommendations
+
+- Use direct `RestApiClient` calls or `useDocyrusClient()` for ACL work; these routes may not be present in generated OpenAPI or collection layers.
+- Prefer role `uid` values from API responses for future writes and filters.
+- Treat `PUT /users/:userId/roles` as the canonical full-sync endpoint.
+- Treat `POST /users/:userId/roles` as an additive convenience endpoint.
+- Send role-query `query` values as raw JSON objects.
+- Omit `tenantAppId` when sending a role query scoped by `dataSourceId`; backend derives it.
+- After deleting a role, invalidate and refetch role lists, user-role lists, role-query lists, and any dependent role-label UI.
+
+## Suggested TypeScript interfaces
+
+```ts
+export interface IAclRole {
+  activitySummaryReportQueryId: string | null;
+  createdBy: string | null;
+  createdOn: string | null;
+  databaseId: string | null;
+  disableLogin: number | null;
+  id: string;
+  lastModifiedBy: string | null;
+  lastModifiedOn: string | null;
+  name: string;
+  ownership: "APP" | "CUSTOM" | "PRODUCT" | "SYSTEM" | "USER";
+  privileges: string;
+  slug: string;
+  status: number | null;
+  tenantAppId: string | null;
+  uid: string;
+}
+
+export interface IAclUserRoleAssignment {
+  createdOn: string | null;
+  id: string;
+  role: {
+    databaseId: string | null;
+    id: string;
+    name: string;
+    slug: string;
+    uid: string;
+  };
+  roleId: string;
+  status: number | null;
+  userId: string;
+}
+
+export interface IAclRoleQuery {
+  createdBy: string | null;
+  createdOn: string | null;
+  dataSourceId: string | null;
+  filterChildRelations: boolean;
+  id: string;
+  lastModifiedBy: string | null;
+  lastModifiedOn: string | null;
+  name: string | null;
+  query: Record<string, unknown> | null;
+  restrictionLevel: "hidden" | "read-only" | "not-deletable";
+  roleIds: string[];
+  tenantAppId: string | null;
+}
+
+export interface IAclRecordShare {
+  id: string;
+  principal_type: "user" | "team" | "role" | "tenant" | "public";
+  principal_id: string;
+  permissions: number;
+  expires_at: string | null;
+  created_by: string | null;
+  created_on: string | null;
+}
+
+export interface IAclEffectiveUserAccess {
+  id: string;
+  user_id: string;
+  permissions: number;
+  source_principal_type: "user" | "team" | "role" | "tenant" | "public";
+  source_principal_id: string;
+}
+```

package/resources/pi-agent/skills/docyrus-api-dev/references/authentication.md

@@ -255,19 +255,16 @@ createRoot(document.getElementById('root')!).render(
 import { useDocyrusAuth, useDocyrusClient, SignInButton } from '@docyrus/signin'
 
 function App() {
-  const { status, user, hasRole, hasPermission, signOut } = useDocyrusAuth()
+  const { status, signOut } = useDocyrusAuth()
   const client = useDocyrusClient()
 
   if (status === 'loading') return <div>Loading...</div>
   if (status === 'unauthenticated') return <SignInButton />
-  if (!user) return <div>Loading profile...</div>
 
   // client is guaranteed non-null when authenticated
   return (
     <div>
       <p>Authenticated!</p>
-      {hasRole('super_admin') && <p>Admin mode enabled</p>}
-      {hasPermission('view', 'projects-data-source-id') && <p>Can view projects</p>}
       <button onClick={() => client!.get('/v1/users/me').then(console.log)}>My Profile</button>
       <button onClick={signOut}>Sign Out</button>
     </div>
@@ -292,8 +289,10 @@ const data = await client!.get('/v1/custom-endpoint')
 
 ## Advanced Usage
 
-Core classes exported for advanced scenarios:
+Core classes and permission functions exported for advanced scenarios:
 
 ```typescript
 import { AuthManager, StandaloneOAuth2Auth, IframeAuth, detectAuthMode } from '@docyrus/signin'
+import { hasRole, hasPermission, getAllRoles } from '@docyrus/signin/core'
+import type { DocyrusUser, DocyrusRole, DocyrusAclRule, AclOperation, PermissionConfig } from '@docyrus/signin/core'
 ```