@docyrus/docyrus 0.0.30 → 0.0.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docyrus/docyrus",
-  "version": "0.0.30",
+  "version": "0.0.32",
   "private": false,
   "description": "Docyrus API CLI",
   "main": "./main.js",
@@ -10,8 +10,8 @@
   "dependencies": {
     "@clack/prompts": "^0.11.0",
     "@hono/node-server": "^1.14.1",
-    "@mariozechner/pi-ai": "0.63.1",
-    "@mariozechner/pi-coding-agent": "0.63.1",
+    "@mariozechner/pi-ai": "0.63.2",
+    "@mariozechner/pi-coding-agent": "0.63.2",
     "@modelcontextprotocol/ext-apps": "^1.2.2",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "@mozilla/readability": "^0.6.0",

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

@@ -0,0 +1,197 @@
+---
+name: docyrus-api-dev
+description: Develop applications using the Docyrus API with @docyrus/api-client and @docyrus/signin libraries. Use when building apps that authenticate with Docyrus OAuth2 (PKCE, iframe, client credentials, device code), make REST API calls to Docyrus data source endpoints, or construct query payloads with filters, aggregations, formulas, pivots, and child queries. Triggers on tasks involving Docyrus API integration, @docyrus/api-client usage, @docyrus/signin authentication, data source query building, or Docyrus REST endpoint consumption.
+---
+
+# Docyrus API Developer
+
+Integrate with the Docyrus API using `@docyrus/api-client` (REST client) and `@docyrus/signin` (React auth provider). Authenticate via OAuth2 PKCE, query data sources with powerful filtering/aggregation, and consume REST endpoints.
+
+## Authentication Quick Start
+
+### React Apps — Use @docyrus/signin
+
+```tsx
+import { DocyrusAuthProvider, useDocyrusAuth, useDocyrusClient, SignInButton } from '@docyrus/signin'
+
+// 1. Wrap root
+<DocyrusAuthProvider
+  apiUrl={import.meta.env.VITE_API_BASE_URL}
+  clientId={import.meta.env.VITE_OAUTH2_CLIENT_ID}
+  redirectUri={import.meta.env.VITE_OAUTH2_REDIRECT_URI}
+  scopes={['offline_access', 'Read.All', 'DS.ReadWrite.All', 'Users.Read']}
+  callbackPath="/auth/callback"
+>
+  <App />
+</DocyrusAuthProvider>
+
+// 2. Use hooks
+function App() {
+  const { status, signOut } = useDocyrusAuth()
+  const client = useDocyrusClient()  // RestApiClient | null
+
+  if (status === 'loading') return <Spinner />
+  if (status === 'unauthenticated') return <SignInButton />
+
+  // client is ready — make API calls
+  const user = await client!.get('/v1/users/me')
+}
+```
+
+### Non-React / Server — Use OAuth2Client Directly
+
+```typescript
+import { RestApiClient, OAuth2Client, OAuth2TokenManagerAdapter, BrowserOAuth2TokenStorage } from '@docyrus/api-client'
+
+const tokenStorage = new BrowserOAuth2TokenStorage(localStorage)
+const oauth2 = new OAuth2Client({
+  baseURL: 'https://api.docyrus.com',
+  clientId: 'your-client-id',
+  redirectUri: 'http://localhost:3000/callback',
+  usePKCE: true,
+  tokenStorage,
+})
+
+// Auth Code flow
+const { url } = await oauth2.getAuthorizationUrl({ scope: 'openid offline_access Users.Read' })
+window.location.href = url
+// After redirect:
+const tokens = await oauth2.handleCallback(window.location.href)
+
+// Create API client with auto-refresh
+const client = new RestApiClient({
+  baseURL: 'https://api.docyrus.com',
+  tokenManager: new OAuth2TokenManagerAdapter(tokenStorage, async () => {
+    return (await oauth2.refreshAccessToken()).accessToken
+  }),
+})
+```
+
+## API Endpoints
+
+### Data Source Items (Dynamic per tenant)
+```
+GET    /v1/apps/{appSlug}/data-sources/{slug}/items          — List with query payload
+GET    /v1/apps/{appSlug}/data-sources/{slug}/items/{id}     — Get one
+POST   /v1/apps/{appSlug}/data-sources/{slug}/items          — Create
+PATCH  /v1/apps/{appSlug}/data-sources/{slug}/items/{id}     — Update
+DELETE /v1/apps/{appSlug}/data-sources/{slug}/items/{id}     — Delete one
+DELETE /v1/apps/{appSlug}/data-sources/{slug}/items          — Delete many (body: { recordIds })
+```
+
+Endpoints exist only if the data source is defined in the tenant. Check the tenant's OpenAPI spec at `GET /v1/api/openapi.json`.
+
+### System Endpoints (Always Available)
+```
+GET    /v1/users          — List users
+POST   /v1/users          — Create user
+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
+// List items with query payload
+const items = await client.get('/v1/apps/base/data-sources/project/items', {
+  columns: 'name, status, record_owner(firstname,lastname)',
+  filters: { rules: [{ field: 'status', operator: '!=', value: 'archived' }] },
+  orderBy: 'created_on DESC',
+  limit: 50,
+})
+
+// Get single item
+const item = await client.get('/v1/apps/base/data-sources/project/items/uuid-here', {
+  columns: 'name, description, status',
+})
+
+// Create
+const newItem = await client.post('/v1/apps/base/data-sources/project/items', {
+  name: 'New Project',
+  status: 'status-enum-id',
+})
+
+// Update
+await client.patch('/v1/apps/base/data-sources/project/items/uuid-here', {
+  name: 'Updated Name',
+})
+
+// Delete
+await client.delete('/v1/apps/base/data-sources/project/items/uuid-here')
+```
+
+## Query Payload Summary
+
+The GET items endpoint accepts a powerful query payload:
+
+| Feature | Purpose |
+|---------|---------|
+| `columns` | Select fields, expand relations `field(subfields)`, alias `alias:field`, spread `...field()` |
+| `filters` | Nested AND/OR groups with 50+ operators (comparison, date shortcuts, user-related) |
+| `filterKeyword` | Full-text search across all searchable fields |
+| `orderBy` | Sort by fields with direction, including related fields |
+| `limit`/`offset` | Pagination (default limit: 100) |
+| `fullCount` | Return total matching count alongside results |
+| `calculations` | Aggregations: count, sum, avg, min, max with grouping |
+| `formulas` | Computed virtual columns (simple functions, block AST, correlated subqueries) |
+| `childQueries` | Fetch related child records as nested JSON arrays |
+| `pivot` | Cross-tab matrix queries with date range series |
+| `expand` | Return full objects for relation/user/enum fields instead of IDs |
+
+**For full query and formula references, read**:
+- `references/data-source-query-guide.md`
+- `references/formula-design-guide-llm.md`
+
+## Critical Rules
+
+1. **Always send `columns`** in list/get calls. Without it, only `id` is returned.
+2. **Data source endpoints are dynamic** — they exist only for data sources defined in the tenant.
+3. **Use `id` field** for `count` calculations. Use the actual field slug for `sum`, `avg`, `min`, `max`.
+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
+
+Read these files when you need detailed information:
+
+- **`references/api-client.md`** — Full RestApiClient API, OAuth2Client (all flows: PKCE, client credentials, device code), token managers, interceptors, error classes, SSE/streaming, file upload/download, HTML to PDF, retry logic
+- **`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