@docyrus/docyrus 0.0.19 → 0.0.20

package/resources/pi-agent/skills/docyrus-platform/references/docyrus-cli-usage.md

@@ -0,0 +1,503 @@
+# Docyrus CLI Usage
+
+Complete command reference for the Docyrus CLI (`@docyrus/docyrus`).
+
+## Global Flags
+
+- `-g, --global` — Use global `~/.docyrus` settings instead of local project settings
+
+---
+
+## auth — Authentication
+
+### `docyrus auth login`
+
+Authorize CLI using OAuth2 device flow or manual token entry.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `--clientId` | string | auto-resolved | OAuth2 client id |
+| `--scope` | string | default scopes | OAuth2 scopes |
+| `--accessToken` | string | — | Manual access token; skips device flow |
+| `--refreshToken` | string | — | Manual refresh token (requires `--accessToken`) |
+
+**Client ID resolution order:** explicit `--clientId` > `DOCYRUS_API_CLIENT_ID` env var > local config > global config > `manual-token` fallback.
+
+**Default scopes:** `openid email profile offline_access ReadWrite.All User.ReadWrite Users.ReadWrite.All Tenant.Read Teams.Read.All DS.ReadWrite.All Docs.ReadWrite.All Architect.ReadWrite.All AI.ReadWrite.All`
+
+### `docyrus auth set-tokens`
+
+Set custom access and refresh tokens for the active environment.
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `--clientId` | string | no | OAuth2 client id |
+| `--scope` | string | no | OAuth2 scopes |
+| `--accessToken` | string | yes | Custom access token |
+| `--refreshToken` | string | no | Custom refresh token |
+
+### `docyrus auth accounts list`
+
+List saved user accounts for the current API base URL.
+
+### `docyrus auth accounts use`
+
+Switch active account by user ID.
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `--userId` | string | yes | User ID to activate |
+
+### `docyrus auth tenants list`
+
+List available tenants for an account.
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `--userId` | string | no | User ID; defaults to active account |
+
+### `docyrus auth tenants use <tenantSelector>`
+
+Switch active tenant for an account.
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `tenantSelector` | string | yes | Tenant number (numeric) or tenant UUID |
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `--userId` | string | no | User ID; defaults to active account |
+| `--scope` | string | no | Scope for tenant bootstrap login if required |
+
+**Note:** Numeric selector = tenant number, non-numeric = UUID.
+
+### `docyrus auth logout`
+
+Revoke and clear all tenant sessions for the active account.
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `--clientId` | string | no | OAuth2 client id override |
+
+### `docyrus auth who`
+
+Return current authenticated user (`/v1/users/me`).
+
+---
+
+## ai — AI Agent Chat
+
+### `docyrus ai "<prompt>"`
+
+Send a prompt to a Docyrus AI agent.
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `prompt` | string | yes | Prompt string (quote when it contains spaces) |
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `--agentId` | string | default agent | Agent ID to use |
+| `--deploymentId` | string | — | Agent deployment ID |
+
+**Output behavior:**
+- TTY mode: renders markdown for human readability
+- `--json`, `--verbose`, or `--format`: preserves structured output
+
+**Response fields:** `agentId`, `deploymentId`, `prompt`, `text`, `reasoning` (optional), `data` (optional).
+
+---
+
+## ds — Data Source Item Operations
+
+### `docyrus ds get <appSlug> <dataSourceSlug>`
+
+Get data source metadata, including its `fields`.
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `appSlug` | string | yes | App slug |
+| `dataSourceSlug` | string | yes | Data source slug |
+
+### `docyrus ds list <appSlug> <dataSourceSlug>`
+
+List data source items with the supported query parameters.
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `appSlug` | string | yes | App slug |
+| `dataSourceSlug` | string | yes | Data source slug |
+
+Most frequently used options:
+
+| Option | Type | Description |
+|---|---|---|
+| `--columns` | string | Column selection |
+| `--filters` | string | JSON filter object |
+| `--filterKeyword` | string | Keyword filter |
+| `--orderBy` | string | Sort order |
+| `--limit` | number | Result limit |
+| `--offset` | number | Result offset |
+
+Advanced options:
+
+| Option | Type | Description |
+|---|---|---|
+| `--collapseRows` | boolean | Collapse rows into a single aggregated array |
+| `--distinctColumns` | string | Distinct columns; comma-separated or JSON array |
+| `--formulas` | string | JSON formulas object |
+| `--calculations` | string | JSON calculations array |
+| `--groupSummaries` | boolean | Return per-group summaries when calculations are used |
+| `--fullCount` | boolean | Include total count |
+| `--expand` | string | Expand columns; comma-separated or JSON array |
+| `--pivot` | string | JSON pivot configuration |
+| `--childQueries` | string | JSON child query array |
+
+### `docyrus ds create <appSlug> <dataSourceSlug>`
+
+Create data source item(s).
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `appSlug` | string | yes | App slug |
+| `dataSourceSlug` | string | yes | Data source slug |
+
+| Option | Type | Description |
+|---|---|---|
+| `--data` | string | JSON payload for record fields |
+| `--fromFile` | string | Path to JSON or CSV file |
+
+**Notes:**
+- Array payloads trigger bulk create (max 50 items per batch)
+- Supports JSON and CSV input files
+
+### `docyrus ds update <appSlug> <dataSourceSlug> [recordId]`
+
+Update data source item(s).
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `appSlug` | string | yes | App slug |
+| `dataSourceSlug` | string | yes | Data source slug |
+| `recordId` | string | for single updates | Record ID |
+
+| Option | Type | Description |
+|---|---|---|
+| `--data` | string | JSON payload for record fields |
+| `--fromFile` | string | Path to JSON or CSV file |
+
+**Notes:**
+- Batch update requires `id` in every item
+- Cannot provide both `recordId` and batch payload
+
+### `docyrus ds delete <appSlug> <dataSourceSlug> <recordId>`
+
+Delete a data source item.
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `appSlug` | string | yes | App slug |
+| `dataSourceSlug` | string | yes | Data source slug |
+| `recordId` | string | yes | Record ID |
+
+---
+
+## discover — OpenAPI Discovery
+
+### `docyrus discover api`
+
+Download tenant OpenAPI spec for the active tenant. Caches locally for subsequent use.
+
+### `docyrus discover namespaces`
+
+List API namespaces from the active tenant's OpenAPI spec.
+
+### `docyrus discover path <prefix>`
+
+List endpoints matching a path prefix.
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `prefix` | string | yes | Path prefix (e.g., `/v1/users`) |
+
+**Note:** Auto-normalizes paths with or without `/v1` prefix.
+
+### `docyrus discover endpoint <selector>`
+
+Return full endpoint details for a path and HTTP method.
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `selector` | string | yes | Path (defaults to GET) or `[METHOD]/path` |
+
+**Examples:**
+- `/v1/users/me` — defaults to GET
+- `[PUT]/v1/users/me/photo` — explicit PUT method
+
+### `docyrus discover entity <name>`
+
+Return full entity schema by name.
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `name` | string | yes | Entity name (e.g., `UserEntity`) |
+
+### `docyrus discover search <query>`
+
+Search endpoint paths and entity names.
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `query` | string | yes | Comma-separated search terms |
+
+---
+
+## apps — App Management
+
+### `docyrus apps list`
+
+List apps.
+
+| Option | Type | Description |
+|---|---|---|
+| `--appType` | string | Filter by app type |
+
+### `docyrus apps delete`
+
+Archive an app (soft delete).
+
+| Option | Type | Description |
+|---|---|---|
+| `--appId` | string | App ID |
+| `--appSlug` | string | App slug |
+
+**Note:** Exactly one of `--appId` or `--appSlug` required.
+
+### `docyrus apps restore`
+
+Restore an archived app.
+
+| Option | Type | Description |
+|---|---|---|
+| `--appId` | string | App ID |
+| `--appSlug` | string | App slug |
+
+### `docyrus apps permanent-delete`
+
+Permanently delete an app.
+
+| Option | Type | Description |
+|---|---|---|
+| `--appId` | string | App ID |
+| `--appSlug` | string | App slug |
+
+---
+
+## studio — Schema Management
+
+Manage data source schemas, fields, and enumerations via the development API.
+
+**Common selector rules:**
+- App: exactly one of `--appId` or `--appSlug`
+- Data source: exactly one of `--dataSourceId` or `--dataSourceSlug` (where supported)
+- Field: exactly one of `--fieldId` or `--fieldSlug` (where supported)
+
+### Data Source Commands
+
+#### `docyrus studio list-data-sources`
+
+| Option | Type | Description |
+|---|---|---|
+| `--appId / --appSlug` | string | App selector |
+| `--expand` | string | Comma-separated expansions (e.g., `fields`) |
+
+#### `docyrus studio get-data-source`
+
+| Option | Type | Description |
+|---|---|---|
+| `--dataSourceId` | string | Data source ID |
+
+Returns the data source metadata together with its `fields`.
+
+#### `docyrus studio create-data-source`
+
+| Option | Type | Description |
+|---|---|---|
+| `--appId / --appSlug` | string | App selector |
+| `--data` | string | JSON payload |
+| `--fromFile` | string | Path to JSON file |
+| `--title` | string | Data source title |
+| `--name` | string | Data source name |
+| `--slug` | string | Data source slug |
+| `--type` | string | Data source type |
+| `--icon` | string | Icon |
+| `--dataSharing` | string | Data sharing mode |
+| `--meta` | string | JSON meta payload |
+
+#### `docyrus studio update-data-source`
+
+Same options as `create-data-source` plus data source selector (`--dataSourceId / --dataSourceSlug`).
+
+#### `docyrus studio delete-data-source`
+
+Archive a data source.
+
+| Option | Type | Description |
+|---|---|---|
+| `--appId / --appSlug` | string | App selector |
+| `--dataSourceId / --dataSourceSlug` | string | Data source selector |
+
+#### `docyrus studio restore-data-source`
+
+Restore an archived data source. Requires `--dataSourceId` (slug resolution not available for archived data sources).
+
+#### `docyrus studio permanent-delete-data-source`
+
+Permanently delete a data source. Requires `--dataSourceId`.
+
+#### `docyrus studio bulk-create-data-sources`
+
+| Option | Type | Description |
+|---|---|---|
+| `--appId / --appSlug` | string | App selector |
+| `--data` | string | JSON payload |
+| `--fromFile` | string | Path to JSON file |
+
+### Field Commands
+
+#### `docyrus studio list-fields`
+
+| Option | Type | Description |
+|---|---|---|
+| `--appId / --appSlug` | string | App selector |
+| `--dataSourceId / --dataSourceSlug` | string | Data source selector |
+
+#### `docyrus studio get-field`
+
+| Option | Type | Description |
+|---|---|---|
+| `--appId / --appSlug` | string | App selector |
+| `--dataSourceId / --dataSourceSlug` | string | Data source selector |
+| `--fieldId / --fieldSlug` | string | Field selector |
+
+#### `docyrus studio create-field`
+
+| Option | Type | Description |
+|---|---|---|
+| `--appId / --appSlug` | string | App selector |
+| `--dataSourceId / --dataSourceSlug` | string | Data source selector |
+| `--data` | string | JSON payload |
+| `--fromFile` | string | Path to JSON file |
+| `--name` | string | Field name |
+| `--slug` | string | Field slug |
+| `--type` | string | Field type |
+| `--readOnly` | boolean | Read only |
+| `--status` | number | Field status |
+| `--defaultValue` | string | Default value |
+| `--relationDataSourceId` | string | Relation target data source ID |
+| `--sortOrder` | number | Sort order |
+| `--tenantEnumSetId` | string | Shared enum set ID |
+| `--options` | string | JSON editor options |
+| `--validations` | string | JSON validations |
+
+#### `docyrus studio update-field`
+
+Same options as `create-field` plus field selector (`--fieldId / --fieldSlug`).
+
+#### `docyrus studio delete-field`
+
+| Option | Type | Description |
+|---|---|---|
+| App, data source, and field selectors | string | See above |
+
+#### `docyrus studio create-fields-batch`
+
+| Option | Type | Description |
+|---|---|---|
+| `--appId / --appSlug` | string | App selector |
+| `--dataSourceId / --dataSourceSlug` | string | Data source selector |
+| `--data` | string | JSON payload |
+| `--fromFile` | string | Path to JSON file |
+
+#### `docyrus studio update-fields-batch`
+
+Same options as `create-fields-batch`.
+
+**Note:** The CLI auto-normalizes payloads: `id → fieldId`, `read_only → readOnly`, `default_value → defaultValue`, `relation_data_source_id → relationDataSourceId`, `options → editorOptions`.
+
+#### `docyrus studio delete-fields-batch`
+
+Same options. Payload key: `fieldIds`.
+
+### Enum Commands
+
+#### `docyrus studio list-enums`
+
+| Option | Type | Description |
+|---|---|---|
+| App, data source, and field selectors | string | See above |
+
+#### `docyrus studio create-enums`
+
+| Option | Type | Description |
+|---|---|---|
+| App, data source, and field selectors | string | See above |
+| `--data` | string | JSON payload |
+| `--fromFile` | string | Path to JSON file |
+| `--enumSetId` | string | Enum set ID |
+
+#### `docyrus studio update-enums`
+
+Same options as `create-enums` (without `--enumSetId`).
+
+**Note:** The CLI auto-normalizes `id → enumId`.
+
+#### `docyrus studio delete-enums`
+
+Same options. Payload key: `enumIds`.
+
+---
+
+## curl — Direct API Requests
+
+### `docyrus curl <path>`
+
+Send arbitrary requests to the Docyrus API.
+
+| Argument | Type | Required | Description |
+|---|---|---|---|
+| `path` | string | yes | API path (no absolute URLs) |
+
+| Option | Type | Description |
+|---|---|---|
+| `-X, --request` | string | HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS) |
+| `-H, --header` | string[] | Request headers (`Key:Value`, repeatable) |
+| `-d, --data` | string | Request payload |
+| `-G, --get` | boolean | Send data as query string |
+| `-i, --include` | boolean | Include status and response headers |
+| `--noAuth` | boolean | Skip Authorization header |
+
+**Notes:**
+- Default method: GET (POST if `-d` provided)
+- Path auto-normalizes `/v1` prefix
+- JSON payloads auto-detect `Content-Type: application/json`
+
+---
+
+## Settings & Persistence
+
+### Storage Locations
+
+| File | Path | Description |
+|---|---|---|
+| Auth state | `<settings>/auth.json` | Multi-account, multi-tenant sessions |
+| Environment config | `<settings>/config.json` | Active environment and client config |
+| OpenAPI cache | `<settings>/tenans/<tenantId>/openapi.json` | Cached tenant OpenAPI specs |
+
+**Default settings root:** `./.docyrus/` (local) or `~/.docyrus/` (global with `-g`).
+
+### Environment Variables
+
+| Variable | Description |
+|---|---|
+| `DOCYRUS_API_CLIENT_ID` | OAuth2 client ID fallback |

package/resources/pi-agent/skills/{docyrus-api-dev → docyrus-platform}/references/formula-design-guide-llm.md

@@ -8,8 +8,6 @@ Two block formula formats:
 
 **Block Subquery** — correlated subquery on child table: `{ alias?, inputs, from: string, with: string | Record<string,string>, filters?: IQueryFilterGroup }`. Detected by `from`+`with`.
 
-Compat wrapper: `{ expression: { from, with, inputs } }` is also accepted.
-
 ## Block Schema
 
 Top-level requires exactly 1 element in `inputs[]`. Optional `alias` becomes SQL alias.
@@ -273,20 +271,16 @@ Allowed: int, int2, int4, int8, bigint, real, float, float4, float8, numeric, do
     {
       "key": "total_tasks",
       "expression": {
-        "expression": {
-          "from": "base_task", "with": "project",
-          "inputs": [{ "kind": "aggregate", "name": "count", "inputs": [{ "kind": "column", "name": "id" }] }]
-        }
+        "from": "base_task", "with": "project",
+        "inputs": [{ "kind": "aggregate", "name": "count", "inputs": [{ "kind": "column", "name": "id" }] }]
       }
     },
     {
       "key": "open_tasks",
       "expression": {
-        "expression": {
-          "from": "base_task", "with": "project",
-          "inputs": [{ "kind": "aggregate", "name": "count", "inputs": [{ "kind": "column", "name": "id" }] }],
-          "filters": { "rules": [{ "field": "status", "operator": "not_in", "value": ["<completed_uuid>", "<cancelled_uuid>"] }], "combinator": "and" }
-        }
+        "from": "base_task", "with": "project",
+        "inputs": [{ "kind": "aggregate", "name": "count", "inputs": [{ "kind": "column", "name": "id" }] }],
+        "filters": { "rules": [{ "field": "status", "operator": "not_in", "value": ["<completed_uuid>", "<cancelled_uuid>"] }], "combinator": "and" }
       }
     }
   ]
@@ -301,18 +295,16 @@ Allowed: int, int2, int4, int8, bigint, real, float, float4, float8, numeric, do
 {
   "key": "task_stats",
   "expression": {
-    "expression": {
-      "from": "base_task", "with": "project",
-      "inputs": [{
-        "kind": "function", "name": "jsonb_build_object",
-        "inputs": [
-          { "kind": "literal", "literal": "total", "cast": "text" },
-          { "kind": "aggregate", "name": "count", "inputs": [{ "kind": "column", "name": "id" }] },
-          { "kind": "literal", "literal": "open", "cast": "text" },
-          { "kind": "aggregate", "name": "count", "inputs": [{ "kind": "case", "cases": [{ "when": { "kind": "compare", "op": "not in", "left": { "kind": "column", "name": "status" }, "right": { "kind": "literal", "literal": ["<completed_uuid>", "<cancelled_uuid>"] } }, "then": { "kind": "column", "name": "id" } }] }] }
-        ]
-      }]
-    }
+    "from": "base_task", "with": "project",
+    "inputs": [{
+      "kind": "function", "name": "jsonb_build_object",
+      "inputs": [
+        { "kind": "literal", "literal": "total", "cast": "text" },
+        { "kind": "aggregate", "name": "count", "inputs": [{ "kind": "column", "name": "id" }] },
+        { "kind": "literal", "literal": "open", "cast": "text" },
+        { "kind": "aggregate", "name": "count", "inputs": [{ "kind": "case", "cases": [{ "when": { "kind": "compare", "op": "not in", "left": { "kind": "column", "name": "status" }, "right": { "kind": "literal", "literal": ["<completed_uuid>", "<cancelled_uuid>"] } }, "then": { "kind": "column", "name": "id" } }] }] }
+      ]
+    }]
   }
 }
 ```

package/resources/pi-agent/skills/docyrus-platform/references/integrations-and-events.md

@@ -0,0 +1,60 @@
+# Integrations & Events
+
+## Connector Framework
+
+- **HTTP providers** — OAuth2-enabled external API integrations (Stripe, Slack, Microsoft, etc.) with custom transformers for request/response mapping
+- **SQL providers** — Direct database connections to external databases
+- **Microsoft integrations** — SharePoint and MS Graph connectors
+
+## Provider Features
+
+- OAuth2 credential management with automatic token refresh
+- Webhook subscription management
+- Configurable pagination
+- Per-tenant and per-user credential isolation
+
+## Webhooks & Events
+
+- Create and manage webhooks with signed verification
+- Event types: data operations, chat platform messages, collaboration events
+- Public webhook keys for external service integration (AI agent, bot, email, portal, webform)
+- File upload support via webhooks
+- Delivery tracking with retry logic
+
+## Content & Document Management
+
+### Collaborative Document Editor
+
+- Real-time collaborative editing
+- Document versioning and history
+- Fragment-based document access
+- Batch document import and version management
+
+### File Management
+
+- File uploads with type validation and size limits
+- Organized folder structures
+- File metadata and association with records
+
+## Messaging & Notifications
+
+### In-App Messaging
+
+- Thread-based conversations
+- Message history with user mentions
+- File sharing in messages
+- Conversation channels embedded in data sources
+
+### Notifications
+
+- Notification center with read/unread tracking
+- Per-type notification preferences
+- Device-based push notifications
+- Email notification delivery
+
+### Email
+
+- Transactional email templates (signup, password reset, invitations, magic links)
+- Custom HTML email templates with dynamic content
+- Email configuration management
+- Delivery tracking and webhook integration

package/resources/pi-agent/skills/docyrus-platform/references/platform-services.md

@@ -0,0 +1,58 @@
+# Platform Services
+
+## Templates & Import/Export
+
+### App Templates
+
+- Pre-built, searchable app templates with categories
+- One-click app creation from templates
+
+### Data Import
+
+- Bulk import via file upload (CSV, JSON)
+- Template-based field mapping
+- Web page import and scraping
+- Migration support from external platforms (Airtable, Monday.com, Notion) with user mapping, field mapping, and batch processing
+
+### Webforms (Public Data Collection)
+
+- Public-facing forms (no authentication required)
+- Form field mapping to data sources
+- Submission webhooks, CAPTCHA support, and response tracking
+
+## Reporting & Analytics
+
+- Custom query templates with variable interpolation
+- Runtime filter application and result pagination
+- Aggregation calculations (count, sum, avg, min, max)
+- Pivot tables and cross-tab matrices
+- Report definitions with widget-based visualizations
+
+## Deployment & Versioning
+
+- Application deployment with streaming logs and status monitoring
+- Deployment history tracking
+- Worker scripts with custom endpoint configuration
+- Git repository integration for version control
+
+## Localization & Navigation
+
+- Multi-language translation management per app
+- Language-specific field labels and locale-aware formatting
+- Custom navigation structures with nested menus, pinning, and favorites
+
+## Platform Administration
+
+- Audit logging with row-level change tracking and user activity history
+- Resource usage tracking and quota management
+- Billing accounts with subscription management
+- System configuration and super admin capabilities
+
+## Security
+
+- Tenant data isolation
+- Encrypted environment variables and secure credential storage
+- Signed webhook verification
+- OAuth2 with PKCE for all authentication flows
+- File validation (type checking, size limits)
+- Input validation at all API boundaries