@synsci/cli-darwin-x64-baseline 1.1.76 → 1.1.78

package/bin/skills/protocolsio-integration/references/file_manager.md

@@ -0,0 +1,412 @@
+# File Manager API
+
+## Overview
+
+The File Manager API enables file operations within protocols.io workspaces, including uploading files, organizing folders, searching content, and managing file lifecycle. This is useful for attaching data files, images, documents, and other resources to protocols.
+
+## Base URL
+
+All file manager endpoints use the base URL: `https://protocols.io/api/v3`
+
+## Search and Browse
+
+### Search Workspace Files
+
+Search for files and folders within a workspace.
+
+**Endpoint:** `GET /workspaces/{workspace_id}/files/search`
+
+**Path Parameters:**
+- `workspace_id`: The workspace's unique identifier
+
+**Query Parameters:**
+- `query`: Search keywords (searches filenames and metadata)
+- `type`: Filter by type
+  - `file`: Files only
+  - `folder`: Folders only
+  - `all`: Both files and folders (default)
+- `folder_id`: Limit search to specific folder
+- `page_size`: Number of results per page (default: 20, max: 100)
+- `page_id`: Page number for pagination (starts at 0)
+
+**Response includes:**
+- File/folder ID and name
+- File size and type
+- Creation and modification dates
+- File path in workspace
+- Download URL (for files)
+
+**Example Request:**
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  "https://protocols.io/api/v3/workspaces/12345/files/search?query=microscopy&type=file"
+```
+
+### List Folder Contents
+
+Browse files and folders within a specific folder.
+
+**Endpoint:** `GET /workspaces/{workspace_id}/folders/{folder_id}`
+
+**Path Parameters:**
+- `workspace_id`: The workspace's unique identifier
+- `folder_id`: The folder's unique identifier (use `root` for workspace root)
+
+**Query Parameters:**
+- `order_by`: Sort field (`name`, `size`, `created`, `modified`)
+- `order_dir`: Sort direction (`asc`, `desc`)
+- `page_size`: Number of results per page
+- `page_id`: Page number for pagination
+
+**Example Request:**
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  "https://protocols.io/api/v3/workspaces/12345/folders/root?order_by=modified&order_dir=desc"
+```
+
+## File Upload
+
+### Upload File
+
+Upload a file to a workspace folder.
+
+**Endpoint:** `POST /workspaces/{workspace_id}/files/upload`
+
+**Request Format**: `multipart/form-data`
+
+**Form Parameters:**
+- `file` (required): The file to upload
+- `folder_id`: Target folder ID (omit or use `root` for workspace root)
+- `name`: Custom filename (optional, uses original filename if omitted)
+- `description`: File description
+- `tags`: Comma-separated tags
+
+**Example Request:**
+```bash
+curl -X POST \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -F "file=@/path/to/local/data.xlsx" \
+  -F "folder_id=67890" \
+  -F "description=Experimental results from trial #3" \
+  -F "tags=experiment,data,2025" \
+  "https://protocols.io/api/v3/workspaces/12345/files/upload"
+```
+
+### Upload Verification
+
+After upload, verify the file was processed correctly.
+
+**Endpoint:** `GET /workspaces/{workspace_id}/files/{file_id}/status`
+
+**Response includes:**
+- Upload status (`processing`, `complete`, `failed`)
+- File metadata
+- Any processing errors
+
+## File Operations
+
+### Download File
+
+Download a file from the workspace.
+
+**Endpoint:** `GET /workspaces/{workspace_id}/files/{file_id}/download`
+
+**Path Parameters:**
+- `workspace_id`: The workspace's unique identifier
+- `file_id`: The file's unique identifier
+
+**Response**: Binary file data with appropriate Content-Type header
+
+**Example Request:**
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  -o "downloaded_file.xlsx" \
+  "https://protocols.io/api/v3/workspaces/12345/files/67890/download"
+```
+
+### Get File Metadata
+
+Retrieve file information without downloading.
+
+**Endpoint:** `GET /workspaces/{workspace_id}/files/{file_id}`
+
+**Response includes:**
+- File name, size, and type
+- Upload date and author
+- Description and tags
+- File path and location
+- Download URL
+- Sharing permissions
+
+### Update File Metadata
+
+Update file description, tags, or other metadata.
+
+**Endpoint:** `PATCH /workspaces/{workspace_id}/files/{file_id}`
+
+**Request Body:**
+- `name`: New filename
+- `description`: Updated description
+- `tags`: Updated tags (comma-separated)
+- `folder_id`: Move to different folder
+
+**Example Request:**
+```bash
+curl -X PATCH \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "description": "Experimental results from trial #3 - REVISED",
+    "tags": "experiment,data,2025,revised"
+  }' \
+  "https://protocols.io/api/v3/workspaces/12345/files/67890"
+```
+
+### Delete File
+
+Move a file to trash (soft delete).
+
+**Endpoint:** `DELETE /workspaces/{workspace_id}/files/{file_id}`
+
+**Note**: Deleted files may be recoverable from trash for a limited time
+
+### Restore File
+
+Restore a deleted file from trash.
+
+**Endpoint:** `POST /workspaces/{workspace_id}/files/{file_id}/restore`
+
+## Folder Operations
+
+### Create Folder
+
+Create a new folder in the workspace.
+
+**Endpoint:** `POST /workspaces/{workspace_id}/folders`
+
+**Request Body:**
+- `name` (required): Folder name
+- `parent_folder_id`: Parent folder ID (omit for workspace root)
+- `description`: Folder description
+
+**Example Request:**
+```bash
+curl -X POST \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "2025 Experiments",
+    "parent_folder_id": "root",
+    "description": "All experimental data from 2025"
+  }' \
+  "https://protocols.io/api/v3/workspaces/12345/folders"
+```
+
+### Rename Folder
+
+**Endpoint:** `PATCH /workspaces/{workspace_id}/folders/{folder_id}`
+
+**Request Body:**
+- `name`: New folder name
+- `description`: Updated description
+
+### Delete Folder
+
+Delete a folder and optionally its contents.
+
+**Endpoint:** `DELETE /workspaces/{workspace_id}/folders/{folder_id}`
+
+**Query Parameters:**
+- `recursive`: Set to `true` to delete folder and all contents (default: `false`)
+
+**Warning**: Recursive deletion cannot be easily undone
+
+## Common Use Cases
+
+### 1. Protocol Data Attachment
+
+Attach experimental data files to protocols:
+
+1. Upload data files: `POST /workspaces/{id}/files/upload`
+2. Verify upload completion
+3. Reference file IDs in protocol steps
+4. Include download links in protocol description
+
+**Example Workflow:**
+```bash
+# Upload the data file
+curl -X POST \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -F "file=@results.csv" \
+  -F "description=Results from protocol execution" \
+  "https://protocols.io/api/v3/workspaces/12345/files/upload"
+
+# Note the file_id from response, then reference in protocol
+```
+
+### 2. Workspace Organization
+
+Organize files into logical folder structures:
+
+1. Create folder hierarchy: `POST /workspaces/{id}/folders`
+2. Upload files to appropriate folders
+3. Use consistent naming conventions
+4. Tag files for easy search
+
+**Example Structure:**
+```
+Workspace Root
+├── Protocols
+│   ├── Published
+│   └── Drafts
+├── Data
+│   ├── Raw
+│   └── Processed
+├── Images
+│   ├── Microscopy
+│   └── Gels
+└── Documents
+    ├── Papers
+    └── Presentations
+```
+
+### 3. File Search and Discovery
+
+Find files across workspace:
+
+1. Search by keywords: `GET /workspaces/{id}/files/search?query=keywords`
+2. Filter by type and date
+3. Download relevant files
+4. Update metadata for better organization
+
+### 4. Batch File Upload
+
+Upload multiple related files:
+
+1. Create target folder
+2. For each file:
+   - Upload file
+   - Verify upload status
+   - Add consistent tags
+3. Create index or manifest file listing all uploads
+
+### 5. Data Backup and Export
+
+Export workspace files for backup:
+
+1. List all folders: `GET /workspaces/{id}/folders/root`
+2. For each folder, list files
+3. Download all files: `GET /workspaces/{id}/files/{file_id}/download`
+4. Maintain folder structure locally
+5. Store metadata separately for restoration
+
+### 6. File Versioning
+
+Manage file versions manually:
+
+1. Upload new version with versioned name (e.g., `data_v2.csv`)
+2. Update previous version metadata to indicate superseded
+3. Maintain version history in folder structure
+4. Reference specific versions in protocols
+
+## Supported File Types
+
+Protocols.io supports various file types:
+
+**Data Files:**
+- Spreadsheets: `.xlsx`, `.xls`, `.csv`, `.tsv`
+- Statistical data: `.rds`, `.rdata`, `.sav`, `.dta`
+- Plain text: `.txt`, `.log`, `.json`, `.xml`
+
+**Images:**
+- Common formats: `.jpg`, `.jpeg`, `.png`, `.gif`, `.bmp`, `.tif`, `.tiff`
+- Scientific: `.czi`, `.nd2`, `.lsm` (may require special handling)
+
+**Documents:**
+- PDF: `.pdf`
+- Word: `.docx`, `.doc`
+- PowerPoint: `.pptx`, `.ppt`
+
+**Code and Scripts:**
+- Python: `.py`, `.ipynb`
+- R: `.r`, `.rmd`
+- Shell: `.sh`, `.bash`
+
+**Multimedia:**
+- Video: `.mp4`, `.avi`, `.mov`
+- Audio: `.mp3`, `.wav`
+
+**Archives:**
+- Compressed: `.zip`, `.tar.gz`, `.7z`
+
+**File Size Limits:**
+- Standard files: Check workspace limits (typically 100 MB - 1 GB)
+- Large files: May require chunked upload or special handling
+
+## Best Practices
+
+1. **File Naming**
+   - Use descriptive, consistent naming conventions
+   - Include dates in ISO format (YYYY-MM-DD)
+   - Avoid special characters and spaces (use underscores)
+   - Example: `experiment_results_2025-10-26.csv`
+
+2. **Organization**
+   - Create logical folder hierarchy
+   - Group related files together
+   - Separate raw data from processed results
+   - Keep protocol-specific files in dedicated folders
+
+3. **Metadata**
+   - Add detailed descriptions
+   - Tag files consistently
+   - Include version information
+   - Document processing steps
+
+4. **Storage Management**
+   - Regularly review and archive old files
+   - Delete unnecessary duplicates
+   - Compress large datasets
+   - Monitor workspace storage limits
+
+5. **Collaboration**
+   - Use clear file names for team members
+   - Document file purposes in descriptions
+   - Maintain consistent folder structures
+   - Communicate major organizational changes
+
+6. **Security**
+   - Avoid uploading sensitive data without proper permissions
+   - Be aware of workspace visibility settings
+   - Use appropriate access controls
+   - Regularly audit file access
+
+## Error Handling
+
+Common error responses:
+
+- `400 Bad Request`: Invalid file format or parameters
+- `401 Unauthorized`: Missing or invalid access token
+- `403 Forbidden`: Insufficient workspace permissions
+- `404 Not Found`: File or folder not found
+- `413 Payload Too Large`: File exceeds size limit
+- `422 Unprocessable Entity`: File validation failed
+- `429 Too Many Requests`: Rate limit exceeded
+- `507 Insufficient Storage`: Workspace storage limit reached
+
+## Performance Considerations
+
+1. **Large Files**
+   - Consider chunked upload for files > 100 MB
+   - Use compression for large datasets
+   - Upload during off-peak hours if possible
+
+2. **Batch Operations**
+   - Implement retry logic for failed uploads
+   - Use exponential backoff for rate limits
+   - Process uploads in parallel where possible
+
+3. **Download Optimization**
+   - Cache frequently accessed files locally
+   - Use streaming for large file downloads
+   - Implement resume capability for interrupted downloads

package/bin/skills/protocolsio-integration/references/protocols_api.md

@@ -0,0 +1,294 @@
+# Protocols API
+
+## Overview
+
+The Protocols API is the core functionality of protocols.io, supporting the complete protocol lifecycle from creation to publication. This includes searching, creating, updating, managing steps, handling materials, bookmarking, and generating PDFs.
+
+## Base URL
+
+All protocol endpoints use the base URL: `https://protocols.io/api/v3`
+
+## Content Format Parameter
+
+Many endpoints support a `content_format` parameter to specify how content is returned:
+
+- `json`: Draft.js JSON format (default)
+- `html`: HTML format
+- `markdown`: Markdown format
+
+Include this as a query parameter: `?content_format=html`
+
+## List and Search Operations
+
+### List Protocols
+
+Retrieve protocols with filtering and pagination.
+
+**Endpoint:** `GET /protocols`
+
+**Query Parameters:**
+- `filter`: Filter type
+  - `public`: Public protocols only
+  - `private`: Your private protocols
+  - `shared`: Protocols shared with you
+  - `user_public`: Another user's public protocols
+- `key`: Search keywords in protocol title, description, and content
+- `order_field`: Sort field (`activity`, `created_on`, `modified_on`, `name`, `id`)
+- `order_dir`: Sort direction (`desc`, `asc`)
+- `page_size`: Number of results per page (default: 10, max: 50)
+- `page_id`: Page number for pagination (starts at 0)
+- `fields`: Comma-separated list of fields to return
+- `content_format`: Content format (`json`, `html`, `markdown`)
+
+**Example Request:**
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  "https://protocols.io/api/v3/protocols?filter=public&key=CRISPR&page_size=20&content_format=html"
+```
+
+### Search by DOI
+
+Retrieve a protocol by its DOI.
+
+**Endpoint:** `GET /protocols/{doi}`
+
+**Path Parameters:**
+- `doi`: The protocol DOI (e.g., `dx.doi.org/10.17504/protocols.io.xxxxx`)
+
+## Retrieve Protocol Details
+
+### Get Protocol by ID
+
+**Endpoint:** `GET /protocols/{protocol_id}`
+
+**Path Parameters:**
+- `protocol_id`: The protocol's unique identifier
+
+**Query Parameters:**
+- `content_format`: Content format (`json`, `html`, `markdown`)
+
+**Response includes:**
+- Protocol metadata (title, authors, description, DOI)
+- All protocol steps with content
+- Materials and reagents
+- Guidelines and warnings
+- Version information
+- Publication status
+
+## Create and Update Protocols
+
+### Create New Protocol
+
+**Endpoint:** `POST /protocols`
+
+**Request Body Parameters:**
+- `title` (required): Protocol title
+- `description`: Protocol description
+- `tags`: Array of tag strings
+- `vendor_name`: Vendor/company name
+- `vendor_link`: Vendor website URL
+- `warning`: Warning or safety message
+- `guidelines`: Usage guidelines
+- `manuscript_citation`: Citation for related manuscript
+- `link`: External link to related resource
+
+**Example Request:**
+```bash
+curl -X POST \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "CRISPR Gene Editing Protocol",
+    "description": "Comprehensive protocol for CRISPR-Cas9 mediated gene editing",
+    "tags": ["CRISPR", "gene editing", "molecular biology"]
+  }' \
+  "https://protocols.io/api/v3/protocols"
+```
+
+### Update Protocol
+
+**Endpoint:** `PATCH /protocols/{protocol_id}`
+
+**Path Parameters:**
+- `protocol_id`: The protocol's unique identifier
+
+**Request Body**: Same parameters as create, all optional
+
+## Protocol Steps Management
+
+### Create Protocol Step
+
+**Endpoint:** `POST /protocols/{protocol_id}/steps`
+
+**Request Body Parameters:**
+- `title` (required): Step title
+- `description`: Step description (HTML, Markdown, or Draft.js JSON)
+- `duration`: Step duration in seconds
+- `temperature`: Temperature setting
+- `components`: Array of materials/reagents used
+- `software`: Software or tools required
+- `commands`: Commands to execute
+- `expected_result`: Expected outcome description
+
+**Example Request:**
+```bash
+curl -X POST \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "Prepare sgRNA",
+    "description": "Design and synthesize single guide RNA (sgRNA) targeting your gene of interest",
+    "duration": 3600,
+    "temperature": 25
+  }' \
+  "https://protocols.io/api/v3/protocols/12345/steps"
+```
+
+### Update Protocol Step
+
+**Endpoint:** `PATCH /protocols/{protocol_id}/steps/{step_id}`
+
+**Parameters**: Same as create step, all optional
+
+### Delete Protocol Step
+
+**Endpoint:** `DELETE /protocols/{protocol_id}/steps/{step_id}`
+
+### Reorder Steps
+
+**Endpoint:** `POST /protocols/{protocol_id}/steps/reorder`
+
+**Request Body:**
+- `step_order`: Array of step IDs in desired order
+
+## Materials and Reagents
+
+### Get Protocol Materials
+
+Retrieve all materials and reagents used in a protocol.
+
+**Endpoint:** `GET /protocols/{protocol_id}/materials`
+
+**Response includes:**
+- Reagent names and descriptions
+- Catalog numbers
+- Vendor information
+- Concentrations and amounts
+- Links to product pages
+
+## Publishing and DOI
+
+### Publish Protocol
+
+Issue a DOI and make the protocol publicly available.
+
+**Endpoint:** `POST /protocols/{protocol_id}/publish`
+
+**Request Body Parameters:**
+- `version_notes`: Description of changes in this version
+- `publish_type`: Publication type
+  - `new`: First publication
+  - `update`: Update to existing published protocol
+
+**Important Notes:**
+- Once published, protocols receive a permanent DOI
+- Published protocols cannot be deleted, only updated with new versions
+- Published protocols are publicly accessible
+
+**Example Request:**
+```bash
+curl -X POST \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "version_notes": "Initial publication",
+    "publish_type": "new"
+  }' \
+  "https://protocols.io/api/v3/protocols/12345/publish"
+```
+
+## Bookmarks
+
+### Add Bookmark
+
+Add a protocol to your bookmarks for quick access.
+
+**Endpoint:** `POST /protocols/{protocol_id}/bookmarks`
+
+### Remove Bookmark
+
+**Endpoint:** `DELETE /protocols/{protocol_id}/bookmarks`
+
+### List Bookmarked Protocols
+
+**Endpoint:** `GET /bookmarks`
+
+## PDF Export
+
+### Generate Protocol PDF
+
+Generate a formatted PDF version of a protocol.
+
+**Endpoint:** `GET /view/{protocol_uri}.pdf`
+
+**Query Parameters:**
+- `compact`: Set to `1` for compact view without large spacing
+
+**Rate Limits:**
+- Signed-in users: 5 requests per minute
+- Unsigned users: 3 requests per minute
+
+**Example:**
+```
+https://protocols.io/api/v3/view/crispr-protocol-abc123.pdf?compact=1
+```
+
+## Common Use Cases
+
+### 1. Import Existing Protocol
+
+To import and work with an existing protocol:
+
+1. Search for the protocol using keywords or DOI
+2. Retrieve full protocol details with `/protocols/{protocol_id}`
+3. Extract steps, materials, and metadata for local use
+
+### 2. Create New Protocol from Scratch
+
+To create a new protocol:
+
+1. Create protocol with title and description: `POST /protocols`
+2. Add steps sequentially: `POST /protocols/{id}/steps`
+3. Review and test the protocol
+4. Publish when ready: `POST /protocols/{id}/publish`
+
+### 3. Update Published Protocol
+
+To update an already-published protocol:
+
+1. Retrieve current version: `GET /protocols/{protocol_id}`
+2. Make necessary updates: `PATCH /protocols/{protocol_id}`
+3. Update or add steps as needed
+4. Publish new version: `POST /protocols/{protocol_id}/publish` with `publish_type: "update"`
+
+### 4. Clone and Modify Protocol
+
+To create a modified version of an existing protocol:
+
+1. Retrieve original protocol details
+2. Create new protocol with modified metadata
+3. Copy and modify steps from original
+4. Publish as new protocol
+
+## Error Handling
+
+Common error responses:
+
+- `400 Bad Request`: Invalid parameters or request format
+- `401 Unauthorized`: Missing or invalid access token
+- `403 Forbidden`: Insufficient permissions for the operation
+- `404 Not Found`: Protocol or resource not found
+- `429 Too Many Requests`: Rate limit exceeded
+- `500 Internal Server Error`: Server-side error
+
+Implement retry logic with exponential backoff for `429` and `500` errors.