@saibolla/ada 0.1.2

package/skills/protocolsio-integration/references/additional_features.md

@@ -0,0 +1,387 @@
+# Additional Features
+
+## Overview
+
+This document covers additional protocols.io API features including user profiles, recently published protocols, experiment records, and notifications.
+
+## Base URL
+
+All endpoints use the base URL: `https://protocols.io/api/v3`
+
+## User Profile Management
+
+### Get User Profile
+
+Retrieve the authenticated user's profile information.
+
+**Endpoint:** `GET /profile`
+
+**Response includes:**
+- User ID and username
+- Full name
+- Email address
+- Affiliation/institution
+- Bio and description
+- Profile image URL
+- Account creation date
+- Protocol count and statistics
+
+**Example Request:**
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  "https://protocols.io/api/v3/profile"
+```
+
+### Update User Profile
+
+Update profile information.
+
+**Endpoint:** `PATCH /profile`
+
+**Request Body:**
+- `first_name`: First name
+- `last_name`: Last name
+- `email`: Email address
+- `affiliation`: Institution or organization
+- `bio`: Profile bio/description
+- `location`: Geographic location
+- `website`: Personal or lab website URL
+- `twitter`: Twitter handle
+- `orcid`: ORCID identifier
+
+**Example Request:**
+```bash
+curl -X PATCH \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "affiliation": "University of Example, Department of Biology",
+    "bio": "Researcher specializing in CRISPR gene editing and molecular biology",
+    "orcid": "0000-0001-2345-6789"
+  }' \
+  "https://protocols.io/api/v3/profile"
+```
+
+### Upload Profile Image
+
+Update profile picture.
+
+**Endpoint:** `POST /profile/image`
+
+**Request Format**: `multipart/form-data`
+
+**Form Parameters:**
+- `image` (required): Image file (JPEG, PNG)
+
+**Recommended specifications:**
+- Minimum size: 200x200 pixels
+- Aspect ratio: Square (1:1)
+- Format: JPEG or PNG
+- Max file size: 5 MB
+
+## Recently Published Protocols
+
+### Query Published Protocols
+
+Discover recently published public protocols.
+
+**Endpoint:** `GET /publications`
+
+**Query Parameters:**
+- `key`: Search keywords
+- `category`: Filter by category
+  - Example categories: `molecular-biology`, `cell-biology`, `biochemistry`, etc.
+- `date_from`: Start date (ISO 8601 format: YYYY-MM-DD)
+- `date_to`: End date
+- `order_field`: Sort field (`published_on`, `title`, `views`)
+- `order_dir`: Sort direction (`desc`, `asc`)
+- `page_size`: Number of results per page (default: 10, max: 50)
+- `page_id`: Page number for pagination
+
+**Example Request:**
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  "https://protocols.io/api/v3/publications?category=molecular-biology&date_from=2025-01-01&order_field=published_on&order_dir=desc"
+```
+
+**Use Cases:**
+- Discover trending protocols
+- Monitor new publications in your field
+- Find recently published protocols for specific techniques
+- Track citation-worthy protocols
+
+## Experiment Records
+
+### Overview
+
+Experiment records allow users to document individual runs or executions of a protocol, tracking what worked, what didn't, and any modifications made.
+
+### Create Experiment Record
+
+Document an execution of a protocol.
+
+**Endpoint:** `POST /protocols/{protocol_id}/runs`
+
+**Path Parameters:**
+- `protocol_id`: The protocol's unique identifier
+
+**Request Body:**
+- `title` (required): Experiment run title
+- `date`: Date of experiment execution (ISO 8601 format)
+- `status`: Experiment outcome
+  - `success`: Experiment succeeded
+  - `partial`: Partially successful
+  - `failed`: Experiment failed
+- `notes`: Detailed notes about the experiment run
+- `modifications`: Protocol modifications or deviations
+- `results`: Summary of results
+- `attachments`: File IDs for data files or images
+
+**Example Request:**
+```bash
+curl -X POST \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "CRISPR Editing - HEK293 Cells - Trial 3",
+    "date": "2025-10-20",
+    "status": "success",
+    "notes": "Successfully achieved 87% editing efficiency. Increased sgRNA concentration from 100nM to 150nM based on previous trials.",
+    "modifications": "Extended incubation time in step 3 from 30 min to 45 min",
+    "results": "Flow cytometry confirmed 87% GFP+ cells after 72h. Western blot showed complete knockout in positive population."
+  }' \
+  "https://protocols.io/api/v3/protocols/12345/runs"
+```
+
+### List Experiment Records
+
+Retrieve all experiment records for a protocol.
+
+**Endpoint:** `GET /protocols/{protocol_id}/runs`
+
+**Query Parameters:**
+- `status`: Filter by outcome (`success`, `partial`, `failed`)
+- `date_from`: Start date
+- `date_to`: End date
+- `page_size`: Number of results per page
+- `page_id`: Page number for pagination
+
+### Update Experiment Record
+
+**Endpoint:** `PATCH /protocols/{protocol_id}/runs/{run_id}`
+
+**Request Body**: Same parameters as create, all optional
+
+### Delete Experiment Record
+
+**Endpoint:** `DELETE /protocols/{protocol_id}/runs/{run_id}`
+
+**Use Cases:**
+- Track reproducibility across multiple experiments
+- Document troubleshooting and optimization
+- Share successful modifications with collaborators
+- Build institutional knowledge base
+- Support lab notebook requirements
+
+## Notifications
+
+### Get User Notifications
+
+Retrieve notifications for the authenticated user.
+
+**Endpoint:** `GET /notifications`
+
+**Query Parameters:**
+- `type`: Filter by notification type
+  - `comment`: New comments on your protocols
+  - `mention`: You were mentioned in a comment
+  - `protocol_update`: Protocol you follow was updated
+  - `workspace`: Workspace activity
+  - `publication`: Protocol was published
+- `read`: Filter by read status
+  - `true`: Only read notifications
+  - `false`: Only unread notifications
+  - Omit for all notifications
+- `page_size`: Number of results per page (default: 20, max: 100)
+- `page_id`: Page number for pagination
+
+**Response includes:**
+- Notification ID and type
+- Message/description
+- Related protocol/comment/workspace
+- Timestamp
+- Read status
+
+**Example Request:**
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  "https://protocols.io/api/v3/notifications?read=false&type=comment"
+```
+
+### Mark Notification as Read
+
+**Endpoint:** `PATCH /notifications/{notification_id}`
+
+**Request Body:**
+- `read`: Set to `true`
+
+### Mark All Notifications as Read
+
+**Endpoint:** `POST /notifications/mark-all-read`
+
+### Delete Notification
+
+**Endpoint:** `DELETE /notifications/{notification_id}`
+
+## Organization Management
+
+### Export Organization Data
+
+Export all protocols and workspace data from an organization.
+
+**Endpoint:** `GET /organizations/{organization_id}/export`
+
+**Path Parameters:**
+- `organization_id`: The organization's unique identifier
+
+**Query Parameters:**
+- `format`: Export format
+  - `json`: JSON format with full metadata
+  - `csv`: CSV format for spreadsheet import
+  - `xml`: XML format
+- `include_files`: Include associated files (`true`/`false`)
+- `include_comments`: Include discussions (`true`/`false`)
+
+**Response**: Download URL for export package
+
+**Use Cases:**
+- Institutional archival
+- Compliance and audit requirements
+- Migration to other systems
+- Backup and disaster recovery
+- Data analysis and reporting
+
+**Example Request:**
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  "https://protocols.io/api/v3/organizations/12345/export?format=json&include_files=true&include_comments=true"
+```
+
+## Common Integration Patterns
+
+### 1. Protocol Discovery and Import
+
+Build a protocol discovery workflow:
+
+```python
+# Search for relevant protocols
+response = requests.get(
+    'https://protocols.io/api/v3/publications',
+    headers={'Authorization': f'Bearer {token}'},
+    params={'key': 'CRISPR', 'category': 'molecular-biology'}
+)
+
+# For each interesting protocol
+for protocol in response.json()['items']:
+    # Get full details
+    details = requests.get(
+        f'https://protocols.io/api/v3/protocols/{protocol["id"]}',
+        headers={'Authorization': f'Bearer {token}'}
+    )
+    # Import to local system
+    import_protocol(details.json())
+```
+
+### 2. Experiment Tracking
+
+Track all protocol executions:
+
+1. Execute protocol in lab
+2. Document execution: `POST /protocols/{id}/runs`
+3. Upload result files to workspace
+4. Link files in experiment record
+5. Analyze success rates across runs
+
+### 3. Notification System Integration
+
+Build custom notification system:
+
+1. Poll for new notifications: `GET /notifications?read=false`
+2. Process each notification type
+3. Send to internal communication system
+4. Mark as read: `PATCH /notifications/{id}`
+
+### 4. Profile Synchronization
+
+Keep profiles synchronized across systems:
+
+1. Retrieve profile: `GET /profile`
+2. Compare with internal system
+3. Update discrepancies
+4. Sync profile images and metadata
+
+## API Response Formats
+
+### Standard Response Structure
+
+Most API responses follow this structure:
+
+```json
+{
+  "status_code": 0,
+  "status_message": "Success",
+  "item": { /* single item data */ },
+  "items": [ /* array of items */ ],
+  "pagination": {
+    "current_page": 0,
+    "total_pages": 5,
+    "page_size": 10,
+    "total_items": 42
+  }
+}
+```
+
+### Error Response Structure
+
+```json
+{
+  "status_code": 400,
+  "status_message": "Bad Request",
+  "error_message": "Missing required parameter: title",
+  "error_details": {
+    "field": "title",
+    "issue": "required"
+  }
+}
+```
+
+## Best Practices
+
+1. **Profile Completeness**
+   - Complete all profile fields
+   - Add ORCID for research attribution
+   - Keep affiliation current
+
+2. **Experiment Documentation**
+   - Document all protocol executions
+   - Include both successes and failures
+   - Note all modifications
+   - Attach relevant data files
+
+3. **Notification Management**
+   - Review notifications regularly
+   - Enable relevant notification types
+   - Disable notification types you don't need
+   - Respond to comments promptly
+
+4. **Publication Discovery**
+   - Set up regular searches for your research area
+   - Follow prolific authors in your field
+   - Bookmark useful protocols
+   - Cite protocols in publications
+
+5. **Data Export**
+   - Export organization data regularly
+   - Test restore procedures
+   - Store exports securely
+   - Document export procedures

package/skills/protocolsio-integration/references/authentication.md

@@ -0,0 +1,100 @@
+# Protocols.io Authentication
+
+## Overview
+
+The protocols.io API supports two types of access tokens for authentication, enabling access to both public and private content.
+
+## Access Token Types
+
+### 1. CLIENT_ACCESS_TOKEN
+
+- **Purpose**: Enables access to public content and the private content of the client user
+- **Use case**: When accessing your own protocols and public protocols
+- **Scope**: Limited to the token owner's private content plus all public content
+
+### 2. OAUTH_ACCESS_TOKEN
+
+- **Purpose**: Grants access to specific users' private content plus all public content
+- **Use case**: When building applications that need to access other users' content with their permission
+- **Scope**: Full access to authorized user's private content plus all public content
+
+## Authentication Header
+
+All API requests must include an Authorization header:
+
+```
+Authorization: Bearer [ACCESS_TOKEN]
+```
+
+## OAuth Flow
+
+### Step 1: Generate Authorization Link
+
+Direct users to the authorization URL to grant access:
+
+```
+GET https://protocols.io/api/v3/oauth/authorize
+```
+
+**Parameters:**
+- `client_id` (required): Your application's client ID
+- `redirect_uri` (required): URL to redirect users after authorization
+- `response_type` (required): Set to "code"
+- `state` (optional but recommended): Random string to prevent CSRF attacks
+
+**Example:**
+```
+https://protocols.io/api/v3/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&state=RANDOM_STRING
+```
+
+### Step 2: Exchange Authorization Code for Token
+
+After user authorization, protocols.io redirects to your `redirect_uri` with an authorization code. Exchange this code for an access token:
+
+```
+POST https://protocols.io/api/v3/oauth/token
+```
+
+**Parameters:**
+- `grant_type`: Set to "authorization_code"
+- `code`: The authorization code received
+- `client_id`: Your application's client ID
+- `client_secret`: Your application's client secret
+- `redirect_uri`: Must match the redirect_uri used in Step 1
+
+**Response includes:**
+- `access_token`: The OAuth access token to use for API requests
+- `token_type`: "Bearer"
+- `expires_in`: Token lifetime in seconds (typically 1 year)
+- `refresh_token`: Token for refreshing the access token
+
+### Step 3: Refresh Access Token
+
+Before the access token expires (typically 1 year), use the refresh token to obtain a new access token:
+
+```
+POST https://protocols.io/api/v3/oauth/token
+```
+
+**Parameters:**
+- `grant_type`: Set to "refresh_token"
+- `refresh_token`: The refresh token received in Step 2
+- `client_id`: Your application's client ID
+- `client_secret`: Your application's client secret
+
+## Rate Limits
+
+Be aware of rate limiting when making API requests:
+
+- **Standard endpoints**: 100 requests per minute per user
+- **PDF endpoint** (`/view/[protocol-uri].pdf`):
+  - Signed-in users: 5 requests per minute
+  - Unsigned users: 3 requests per minute
+
+## Best Practices
+
+1. **Store tokens securely**: Never expose access tokens in client-side code or version control
+2. **Handle token expiration**: Implement automatic token refresh before expiration
+3. **Respect rate limits**: Implement exponential backoff for rate limit errors
+4. **Use state parameter**: Always include a state parameter in OAuth flow for security
+5. **Validate redirect_uri**: Ensure redirect URIs match exactly between authorization and token requests

package/skills/protocolsio-integration/references/discussions.md

@@ -0,0 +1,225 @@
+# Discussions API
+
+## Overview
+
+The Discussions API enables collaborative commenting on protocols. Comments can be added at both the protocol level and the individual step level, with support for threaded replies, editing, and deletion.
+
+## Base URL
+
+All discussion endpoints use the base URL: `https://protocols.io/api/v3`
+
+## Protocol-Level Comments
+
+### List Protocol Comments
+
+Retrieve all comments for a protocol.
+
+**Endpoint:** `GET /protocols/{protocol_id}/comments`
+
+**Path Parameters:**
+- `protocol_id`: The protocol's unique identifier
+
+**Query Parameters:**
+- `page_size`: Number of results per page (default: 10, max: 50)
+- `page_id`: Page number for pagination (starts at 0)
+
+**Response includes:**
+- Comment ID and content
+- Author information (name, affiliation, avatar)
+- Timestamp (created and modified)
+- Reply count and thread structure
+
+### Create Protocol Comment
+
+Add a new comment to a protocol.
+
+**Endpoint:** `POST /protocols/{protocol_id}/comments`
+
+**Request Body:**
+- `body` (required): Comment text (supports HTML or Markdown)
+- `parent_comment_id` (optional): ID of parent comment for threaded replies
+
+**Example Request:**
+```bash
+curl -X POST \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "body": "This protocol worked excellently for our CRISPR experiments. We achieved 85% editing efficiency."
+  }' \
+  "https://protocols.io/api/v3/protocols/12345/comments"
+```
+
+### Create Threaded Reply
+
+To reply to an existing comment, include the parent comment ID:
+
+```bash
+curl -X POST \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "body": "What cell type did you use?",
+    "parent_comment_id": 67890
+  }' \
+  "https://protocols.io/api/v3/protocols/12345/comments"
+```
+
+### Update Comment
+
+Edit your own comment.
+
+**Endpoint:** `PATCH /protocols/{protocol_id}/comments/{comment_id}`
+
+**Request Body:**
+- `body` (required): Updated comment text
+
+**Authorization**: Only the comment author can edit their comments
+
+### Delete Comment
+
+Remove a comment.
+
+**Endpoint:** `DELETE /protocols/{protocol_id}/comments/{comment_id}`
+
+**Authorization**: Only the comment author can delete their comments
+
+**Note**: Deleting a parent comment may affect the entire thread, depending on API implementation
+
+## Step-Level Comments
+
+### List Step Comments
+
+Retrieve all comments for a specific protocol step.
+
+**Endpoint:** `GET /protocols/{protocol_id}/steps/{step_id}/comments`
+
+**Path Parameters:**
+- `protocol_id`: The protocol's unique identifier
+- `step_id`: The step's unique identifier
+
+**Query Parameters:**
+- `page_size`: Number of results per page
+- `page_id`: Page number for pagination
+
+### Create Step Comment
+
+Add a comment to a specific step.
+
+**Endpoint:** `POST /protocols/{protocol_id}/steps/{step_id}/comments`
+
+**Request Body:**
+- `body` (required): Comment text
+- `parent_comment_id` (optional): ID of parent comment for replies
+
+**Example Request:**
+```bash
+curl -X POST \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "body": "At this step, we found that increasing the incubation time to 2 hours improved results significantly."
+  }' \
+  "https://protocols.io/api/v3/protocols/12345/steps/67890/comments"
+```
+
+### Update Step Comment
+
+**Endpoint:** `PATCH /protocols/{protocol_id}/steps/{step_id}/comments/{comment_id}`
+
+**Request Body:**
+- `body` (required): Updated comment text
+
+### Delete Step Comment
+
+**Endpoint:** `DELETE /protocols/{protocol_id}/steps/{step_id}/comments/{comment_id}`
+
+## Common Use Cases
+
+### 1. Discussion Thread Analysis
+
+To analyze discussions around a protocol:
+
+1. Retrieve protocol comments: `GET /protocols/{id}/comments`
+2. For each step, retrieve step-specific comments
+3. Build a discussion thread tree using `parent_comment_id`
+4. Analyze feedback patterns and common issues
+
+### 2. Collaborative Protocol Improvement
+
+To gather feedback on a protocol:
+
+1. Publish the protocol
+2. Monitor new comments: `GET /protocols/{id}/comments`
+3. Respond to questions with threaded replies
+4. Update protocol based on feedback
+5. Publish updated version with notes acknowledging contributors
+
+### 3. Community Engagement
+
+To engage with protocol users:
+
+1. Set up monitoring for new comments on your protocols
+2. Respond promptly to questions and issues
+3. Use step-level comments to provide detailed clarifications
+4. Create threaded discussions for complex topics
+
+### 4. Protocol Troubleshooting
+
+To document troubleshooting experiences:
+
+1. Identify problematic steps in a protocol
+2. Add step-level comments with specific issues encountered
+3. Document solutions or workarounds
+4. Create a discussion thread with other users experiencing similar issues
+
+## Comment Formatting
+
+Comments support rich text formatting:
+
+- **HTML**: Use standard HTML tags for formatting
+- **Markdown**: Use Markdown syntax for simpler formatting
+- **Links**: Include URLs to related resources or publications
+- **Mentions**: Reference other users (format may vary)
+
+**Example with Markdown:**
+```json
+{
+  "body": "## Important Note\n\nWe achieved better results with:\n\n- Increasing temperature to 37°C\n- Extending incubation to 2 hours\n- Using freshly prepared reagents\n\nSee our publication: [doi:10.xxxx/xxxxx](https://doi.org/...)"
+}
+```
+
+## Best Practices
+
+1. **Be specific**: When commenting on steps, reference specific parameters or conditions
+2. **Provide context**: Include relevant experimental details (cell type, reagent batch, equipment)
+3. **Use step-level comments**: Direct feedback to specific steps rather than protocol-level when appropriate
+4. **Engage constructively**: Respond to questions and feedback promptly
+5. **Update protocols**: Incorporate validated feedback into protocol updates
+6. **Thread related discussions**: Use reply functionality to keep related comments together
+7. **Document variations**: Share protocol modifications that worked in your hands
+
+## Permissions and Privacy
+
+- **Public protocols**: Anyone can comment on published public protocols
+- **Private protocols**: Only collaborators with access can comment
+- **Comment ownership**: Only comment authors can edit or delete their comments
+- **Moderation**: Protocol authors may have additional moderation capabilities
+
+## Error Handling
+
+Common error responses:
+
+- `400 Bad Request`: Invalid comment format or missing required fields
+- `401 Unauthorized`: Missing or invalid access token
+- `403 Forbidden`: Insufficient permissions (e.g., trying to edit another user's comment)
+- `404 Not Found`: Protocol, step, or comment not found
+- `429 Too Many Requests`: Rate limit exceeded
+
+## Notifications
+
+Comments may trigger notifications:
+
+- Protocol authors receive notifications for new comments
+- Comment authors receive notifications for replies
+- Users can manage notification preferences in their account settings