@saibolla/ada 0.1.2

package/skills/pyzotero/references/pagination.md

@@ -0,0 +1,79 @@
+# Pagination: follow(), everything(), Generators
+
+Pyzotero returns 100 items by default. Use these methods to retrieve more.
+
+## everything() — Retrieve All Results
+
+The simplest way to get all items:
+
+```python
+# All items in the library
+all_items = zot.everything(zot.items())
+
+# All top-level items
+all_top = zot.everything(zot.top())
+
+# All items in a collection
+all_col = zot.everything(zot.collection_items('COLKEY'))
+
+# All items matching a search
+all_results = zot.everything(zot.items(q='machine learning', itemType='journalArticle'))
+```
+
+`everything()` works with all Read API calls that can return multiple items.
+
+## follow() — Sequential Pagination
+
+```python
+# Retrieve items in batches, manually advancing the page
+first_batch = zot.top(limit=25)
+second_batch = zot.follow()   # next 25 items
+third_batch = zot.follow()    # next 25 items
+```
+
+**Warning**: `follow()` raises `StopIteration` when no more items are available. Not valid after single-item calls like `zot.item()`.
+
+## iterfollow() — Generator
+
+```python
+# Create a generator over follow()
+first = zot.top(limit=10)
+lazy = zot.iterfollow()
+
+# Retrieve subsequent pages
+second = next(lazy)
+third = next(lazy)
+```
+
+## makeiter() — Generator over Any Method
+
+```python
+# Create a generator directly from a method call
+gen = zot.makeiter(zot.top(limit=25))
+
+page1 = next(gen)  # first 25 items
+page2 = next(gen)  # next 25 items
+# Raises StopIteration when exhausted
+```
+
+## Manual start/limit Pagination
+
+```python
+page_size = 50
+offset = 0
+
+while True:
+    batch = zot.items(limit=page_size, start=offset)
+    if not batch:
+        break
+    # process batch
+    for item in batch:
+        process(item)
+    offset += page_size
+```
+
+## Performance Notes
+
+- `everything()` makes multiple API calls sequentially; large libraries may take time.
+- For libraries with thousands of items, use `since=version` to retrieve only changed items (useful for sync workflows).
+- All of `follow()`, `everything()`, and `makeiter()` are only valid for methods that return multiple items.

package/skills/pyzotero/references/read-api.md

@@ -0,0 +1,137 @@
+# Read API Methods
+
+## Retrieving Items
+
+```python
+# All items in library (100 per call by default)
+items = zot.items()
+
+# Top-level items only (excludes attachments/notes that are children)
+top = zot.top(limit=25)
+
+# A specific item by key
+item = zot.item('ITEMKEY')
+
+# Multiple specific items (up to 50 per call)
+subset = zot.get_subset(['KEY1', 'KEY2', 'KEY3'])
+
+# Items from trash
+trash = zot.trash()
+
+# Deleted items (requires 'since' parameter)
+deleted = zot.deleted(since=1000)
+
+# Items from "My Publications"
+pubs = zot.publications()  # user libraries only
+
+# Count all items
+count = zot.count_items()
+
+# Count top-level items
+n = zot.num_items()
+```
+
+## Item Data Structure
+
+Items are returned as dicts. Data lives in `item['data']`:
+
+```python
+item = zot.item('VDNIEAPH')[0]
+title = item['data']['title']
+item_type = item['data']['itemType']
+creators = item['data']['creators']
+tags = item['data']['tags']
+key = item['data']['key']
+version = item['data']['version']
+collections = item['data']['collections']
+doi = item['data'].get('DOI', '')
+```
+
+## Child Items
+
+```python
+# Get child items (notes, attachments) of a parent
+children = zot.children('PARENTKEY')
+```
+
+## Retrieving Collections
+
+```python
+# All collections (including subcollections)
+collections = zot.collections()
+
+# Top-level collections only
+top_collections = zot.collections_top()
+
+# A specific collection
+collection = zot.collection('COLLECTIONKEY')
+
+# Sub-collections of a collection
+sub = zot.collections_sub('COLLECTIONKEY')
+
+# All collections and sub-collections in a flat list
+all_cols = zot.all_collections()
+# Or from a specific collection down:
+all_cols = zot.all_collections('COLLECTIONKEY')
+
+# Items in a specific collection (not sub-collections)
+col_items = zot.collection_items('COLLECTIONKEY')
+
+# Top-level items in a specific collection
+col_top = zot.collection_items_top('COLLECTIONKEY')
+
+# Count items in a collection
+n = zot.num_collectionitems('COLLECTIONKEY')
+```
+
+## Retrieving Tags
+
+```python
+# All tags in the library
+tags = zot.tags()
+
+# Tags from a specific item
+item_tags = zot.item_tags('ITEMKEY')
+
+# Tags in a collection
+col_tags = zot.collection_tags('COLLECTIONKEY')
+```
+
+## Retrieving Groups
+
+```python
+groups = zot.groups()
+# Returns list of group libraries accessible to current key
+```
+
+## Version Information
+
+```python
+# Last modified version of the library
+version = zot.last_modified_version()
+
+# Item versions dict {key: version}
+item_versions = zot.item_versions()
+
+# Collection versions dict {key: version}
+col_versions = zot.collection_versions()
+
+# Changes since a known version (for syncing)
+changed_items = zot.item_versions(since=1000)
+```
+
+## Library Settings
+
+```python
+settings = zot.settings()
+# Returns synced settings (feeds, PDF reading progress, etc.)
+# Use 'since' to get only changes:
+new_settings = zot.settings(since=500)
+```
+
+## Saved Searches
+
+```python
+searches = zot.searches()
+# Retrieves saved search metadata (not results)
+```

package/skills/pyzotero/references/saved-searches.md

@@ -0,0 +1,77 @@
+# Saved Searches
+
+## Retrieving Saved Searches
+
+```python
+# Get all saved search metadata (not results)
+searches = zot.searches()
+# Returns list of dicts with name, key, conditions, version
+
+for search in searches:
+    print(search['data']['name'], search['data']['key'])
+```
+
+**Note**: Saved search *results* cannot be retrieved via the API (as of 2025). Only metadata is returned.
+
+## Creating Saved Searches
+
+Each condition dict must have `condition`, `operator`, and `value`:
+
+```python
+conditions = [
+    {
+        'condition': 'title',
+        'operator': 'contains',
+        'value': 'machine learning'
+    }
+]
+zot.saved_search('ML Papers', conditions)
+```
+
+### Multiple Conditions (AND logic)
+
+```python
+conditions = [
+    {'condition': 'itemType', 'operator': 'is', 'value': 'journalArticle'},
+    {'condition': 'tag', 'operator': 'is', 'value': 'unread'},
+    {'condition': 'date', 'operator': 'isAfter', 'value': '2023-01-01'},
+]
+zot.saved_search('Recent Unread Articles', conditions)
+```
+
+## Deleting Saved Searches
+
+```python
+# Get search keys first
+searches = zot.searches()
+keys = [s['data']['key'] for s in searches if s['data']['name'] == 'Old Search']
+zot.delete_saved_search(keys)
+```
+
+## Discovering Valid Operators and Conditions
+
+```python
+# All available operators
+operators = zot.show_operators()
+
+# All available conditions
+conditions = zot.show_conditions()
+
+# Operators valid for a specific condition
+title_operators = zot.show_condition_operators('title')
+# e.g. ['is', 'isNot', 'contains', 'doesNotContain', 'beginsWith']
+```
+
+## Common Condition/Operator Combinations
+
+| Condition | Common Operators |
+|-----------|-----------------|
+| `title` | `contains`, `doesNotContain`, `is`, `beginsWith` |
+| `tag` | `is`, `isNot` |
+| `itemType` | `is`, `isNot` |
+| `date` | `isBefore`, `isAfter`, `is` |
+| `creator` | `contains`, `is` |
+| `publicationTitle` | `contains`, `is` |
+| `year` | `is`, `isBefore`, `isAfter` |
+| `collection` | `is`, `isNot` |
+| `fulltextContent` | `contains` |

package/skills/pyzotero/references/search-params.md

@@ -0,0 +1,90 @@
+# Search & Request Parameters
+
+Parameters can be passed directly to any Read API call, or set globally with `add_parameters()`.
+
+```python
+# Inline parameters (valid for one call only)
+results = zot.items(q='climate change', limit=50, sort='date', direction='desc')
+
+# Set globally (overridden by inline params on the next call)
+zot.add_parameters(limit=50, sort='dateAdded')
+results = zot.items()
+```
+
+## Available Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `q` | str | Quick search — titles and creator fields by default |
+| `qmode` | str | `'titleCreatorYear'` (default) or `'everything'` (full-text) |
+| `itemType` | str | Filter by item type. See search syntax for operators |
+| `tag` | str or list | Filter by tag(s). Multiple tags = AND logic |
+| `since` | int | Return only objects modified after this library version |
+| `sort` | str | Sort field (see below) |
+| `direction` | str | `'asc'` or `'desc'` |
+| `limit` | int | 1–100, or `None` |
+| `start` | int | Offset into result set |
+| `format` | str | Response format (see exports.md) |
+| `itemKey` | str | Comma-separated item keys (up to 50) |
+| `content` | str | `'bib'`, `'html'`, `'citation'`, or export format |
+| `style` | str | CSL style name (used with `content='bib'`) |
+| `linkwrap` | str | `'1'` to wrap URLs in `<a>` tags in bibliography output |
+
+## Sort Fields
+
+`dateAdded`, `dateModified`, `title`, `creator`, `type`, `date`, `publisher`,
+`publicationTitle`, `journalAbbreviation`, `language`, `accessDate`,
+`libraryCatalog`, `callNumber`, `rights`, `addedBy`, `numItems`, `tags`
+
+## Tag Search Syntax
+
+```python
+# Single tag
+zot.items(tag='machine learning')
+
+# Multiple tags — AND logic (items must have all tags)
+zot.items(tag=['climate', 'adaptation'])
+
+# OR logic (items with any tag)
+zot.items(tag='climate OR adaptation')
+
+# Exclude a tag
+zot.items(tag='-retracted')
+```
+
+## Item Type Filtering
+
+```python
+# Single type
+zot.items(itemType='journalArticle')
+
+# OR multiple types
+zot.items(itemType='journalArticle || book')
+
+# Exclude a type
+zot.items(itemType='-note')
+```
+
+Common item types: `journalArticle`, `book`, `bookSection`, `conferencePaper`,
+`thesis`, `report`, `dataset`, `preprint`, `note`, `attachment`, `webpage`,
+`patent`, `statute`, `case`, `hearing`, `interview`, `letter`, `manuscript`,
+`map`, `artwork`, `audioRecording`, `videoRecording`, `podcast`, `film`,
+`radioBroadcast`, `tvBroadcast`, `presentation`, `encyclopediaArticle`,
+`dictionaryEntry`, `forumPost`, `blogPost`, `instantMessage`, `email`,
+`document`, `computerProgram`, `bill`, `newspaperArticle`, `magazineArticle`
+
+## Examples
+
+```python
+# Recent journal articles matching query, sorted by date
+zot.items(q='CRISPR', itemType='journalArticle', sort='date', direction='desc', limit=20)
+
+# Items added since a known library version
+zot.items(since=4000)
+
+# Items with a specific tag, offset for pagination
+zot.items(tag='to-read', limit=25, start=25)
+
+# Full-text search
+zot.items(q='gene editing', qmode='everything', limit=10)
+```

package/skills/pyzotero/references/tags.md

@@ -0,0 +1,87 @@
+# Tag Management
+
+## Retrieving Tags
+
+```python
+# All tags in the library
+tags = zot.tags()
+# Returns list of strings: ['climate change', 'machine learning', ...]
+
+# Tags for a specific item
+item_tags = zot.item_tags('ITEMKEY')
+
+# Tags in a specific collection
+col_tags = zot.collection_tags('COLKEY')
+
+# Filter tags by prefix (e.g. all tags starting with 'bio')
+filtered = zot.tags(q='bio')
+```
+
+## Adding Tags to Items
+
+```python
+# Add one or more tags to an item (retrieves item first)
+item = zot.item('ITEMKEY')
+updated = zot.add_tags(item, 'tag1', 'tag2', 'tag3')
+
+# Add a list of tags
+tag_list = ['reviewed', 'high-priority', '2024']
+updated = zot.add_tags(item, *tag_list)
+```
+
+## Deleting Tags
+
+```python
+# Delete specific tags from the library
+zot.delete_tags('old-tag', 'unused-tag')
+
+# Delete a list of tags
+tags_to_remove = ['deprecated', 'temp']
+zot.delete_tags(*tags_to_remove)
+```
+
+## Searching Items by Tag
+
+```python
+# Items with a single tag
+items = zot.items(tag='machine learning')
+
+# Items with multiple tags (AND logic)
+items = zot.items(tag=['climate', 'adaptation'])
+
+# Items with any of these tags (OR logic)
+items = zot.items(tag='climate OR sea level')
+
+# Items NOT having a tag
+items = zot.items(tag='-retracted')
+```
+
+## Batch Tag Operations
+
+```python
+# Add a tag to all items in a collection
+items = zot.everything(zot.collection_items('COLKEY'))
+for item in items:
+    zot.add_tags(item, 'collection-reviewed')
+
+# Find all items with a specific tag and retag them
+old_tag_items = zot.everything(zot.items(tag='old-name'))
+for item in old_tag_items:
+    # Add new tag
+    item['data']['tags'].append({'tag': 'new-name'})
+    # Remove old tag
+    item['data']['tags'] = [t for t in item['data']['tags'] if t['tag'] != 'old-name']
+zot.update_items(old_tag_items)
+```
+
+## Tag Types
+
+Zotero has two tag types stored in `tag['type']`:
+- `0` — User-added tags (default)
+- `1` — Automatically imported tags (from bibliographic databases)
+
+```python
+item = zot.item('ITEMKEY')
+for tag in item['data']['tags']:
+    print(tag['tag'], tag.get('type', 0))
+```

package/skills/pyzotero/references/write-api.md

@@ -0,0 +1,123 @@
+# Write API Methods
+
+## Creating Items
+
+Always use `item_template()` to get a valid template before creating items.
+
+```python
+# Get a template for a specific item type
+template = zot.item_template('journalArticle')
+
+# Fill in fields
+template['title'] = 'Deep Learning for Genomics'
+template['date'] = '2024'
+template['publicationTitle'] = 'Nature Methods'
+template['volume'] = '21'
+template['DOI'] = '10.1038/s41592-024-02233-6'
+template['creators'] = [
+    {'creatorType': 'author', 'firstName': 'Jane', 'lastName': 'Doe'},
+    {'creatorType': 'author', 'firstName': 'John', 'lastName': 'Smith'},
+]
+
+# Validate fields before creating (raises InvalidItemFields if invalid)
+zot.check_items([template])
+
+# Create the item
+resp = zot.create_items([template])
+# resp: {'success': {'0': 'NEWITEMKEY'}, 'failed': {}, 'unchanged': {}}
+new_key = resp['success']['0']
+```
+
+### Create Multiple Items at Once
+
+```python
+templates = []
+for data in paper_data_list:
+    t = zot.item_template('journalArticle')
+    t['title'] = data['title']
+    t['DOI'] = data['doi']
+    templates.append(t)
+
+resp = zot.create_items(templates)
+```
+
+### Create Child Items
+
+```python
+# Create a note as a child of an existing item
+note_template = zot.item_template('note')
+note_template['note'] = '<p>My annotation here</p>'
+zot.create_items([note_template], parentid='PARENTKEY')
+```
+
+## Updating Items
+
+```python
+# Retrieve, modify, update
+item = zot.item('ITEMKEY')
+item['data']['title'] = 'Updated Title'
+item['data']['abstractNote'] = 'New abstract text.'
+success = zot.update_item(item)  # returns True or raises error
+
+# Update many items at once (auto-chunked at 50)
+items = zot.items(limit=10)
+for item in items:
+    item['data']['extra'] += '\nProcessed'
+zot.update_items(items)
+```
+
+## Deleting Items
+
+```python
+# Must retrieve item first (version field is required)
+item = zot.item('ITEMKEY')
+zot.delete_item([item])
+
+# Delete multiple items
+items = zot.items(tag='to-delete')
+zot.delete_item(items)
+```
+
+## Item Types and Fields
+
+```python
+# All available item types
+item_types = zot.item_types()
+# [{'itemType': 'artwork', 'localized': 'Artwork'}, ...]
+
+# All available fields
+fields = zot.item_fields()
+
+# Valid fields for a specific item type
+journal_fields = zot.item_type_fields('journalArticle')
+
+# Valid creator types for an item type
+creator_types = zot.item_creator_types('journalArticle')
+# [{'creatorType': 'author', 'localized': 'Author'}, ...]
+
+# All localised creator field names
+creator_fields = zot.creator_fields()
+
+# Attachment link modes (needed for attachment templates)
+link_modes = zot.item_attachment_link_modes()
+
+# Template for an attachment
+attach_template = zot.item_template('attachment', linkmode='imported_file')
+```
+
+## Optimistic Locking
+
+Use `last_modified` to prevent overwriting concurrent changes:
+
+```python
+# Only update if library version matches
+zot.update_item(item, last_modified=4025)
+# Raises an error if the server version differs
+```
+
+## Notes
+
+- `create_items()` accepts up to 50 items per call; batch if needed.
+- `update_items()` auto-chunks at 50 items.
+- If a dict passed to `create_items()` contains a `key` matching an existing item, it will be updated rather than created.
+- Always call `check_items()` before `create_items()` to catch field errors early.