studiograph 1.1.3 → 1.2.0-beta.10

package/dist/agent/skills/obsidian-source-setup.md

@@ -0,0 +1,246 @@
+---
+name: obsidian-source-setup
+description: Scaffold an Obsidian vault into a sync source config — explore vault structure, map directories to entity types, build field maps from frontmatter
+loading: on-demand
+---
+
+# Obsidian Source Setup
+
+Guide for mapping any Obsidian vault to a Studiograph sync source config. Every vault is different — follow these steps to explore the vault and build a config tailored to its structure.
+
+## Step 1: Explore the Vault
+
+Before writing any config, understand the vault's organization.
+
+1. **List top-level directories** — use the Obsidian MCP connector or read the filesystem directly:
+   - Note every top-level folder name
+   - Identify which are content folders vs system folders (`.obsidian/`, `.smart-env/`, `Attachments/`, `Templates/`)
+   - Check for subdirectory structure (e.g., `Organizations/Clients/`, `Organizations/Vendors/`)
+
+2. **Count files per directory** — understand the scale:
+   - Large directories (100+) are likely core entity types
+   - Small directories (<10) may not be worth a dedicated mapping
+
+3. **Check for nested content** — some vaults use flat files, others use subfolders:
+   - `People/John Smith.md` (flat) — each file is one entity
+   - `Projects/Acme/Acme.md` + `Projects/Acme/SOW.md` (nested) — folder per entity with sub-documents
+
+## Step 2: Sample Frontmatter
+
+Read the first 25-30 lines of 2-3 files per directory to see what YAML frontmatter exists.
+
+**Key things to look for:**
+- Which fields are present (even if empty)
+- Wikilink references: `client: "[[Acme Corp]]"` or `related_people: ["[[John Smith]]"]`
+- Tag conventions: `tags: [project/active]`, `tags: ["#person"]`, `tags: [sop, operations]`
+- Date formats: `date: 2026-01-15`, `start_date: 2026-01-15`
+- Status encoding: frontmatter `status:` field vs tag-based `tags: [project/active]`
+
+**Frontmatter vs no frontmatter:**
+- Files WITH frontmatter (YAML between `---` fences) → use `frontmatter` extraction mode
+- Files WITHOUT frontmatter (plain markdown) → use `unstructured` mode (LLM extraction, slower)
+- If a directory has a mix, prefer `frontmatter` — files without frontmatter will be skipped, which is often acceptable
+
+## Step 3: Map Directories to Entity Types
+
+For each content directory, decide which Studiograph entity type it maps to. Use the directory name, file content, and frontmatter fields as signals.
+
+### Entity Type Reference
+
+**Project repo types** (time-bound, engagement-specific):
+| Type | Use when | Key fields |
+|------|----------|------------|
+| `project` | Client engagements, initiatives | name, client, start_date, end_date, status, team |
+| `meeting` | Meetings, events, conferences | name, date, attendees, agenda, action_items |
+| `task` | Action items, tickets | name, assignee, due_date, status, priority |
+| `deliverable` | Outputs, milestones | name, project, status, due_date |
+| `brief` | Project briefs, RFPs | project_name, client, objectives |
+| `artifact` | Files, documents, assets | name, type, project, url |
+| `decision` | Architectural/business decisions | title, date, status, rationale |
+
+**Function repo types** (operational, cross-project):
+| Type | Use when | Key fields |
+|------|----------|------------|
+| `person` | People, contacts, team members | name, role, email, status, organization |
+| `client` | Companies, organizations (as clients) | name, type, status, industry, contacts |
+| `vendor` | Vendors, partners, freelancers | name, type, status, services |
+| `deal` | Sales pipeline entries | name, client, stage, deal_value |
+| `proposal` | Proposals, SOWs | name, client, status, deliverables |
+| `contract` | Contracts, agreements | name, type, client, status |
+| `financial-plan` | Budgets, rate cards, P&L | name, type, period |
+| `role` | Job descriptions, org structure | title, department, level, type |
+
+**Shared resource types** (reference, reusable):
+| Type | Use when | Key fields |
+|------|----------|------------|
+| `process` | SOPs, workflows, methodologies | name, description, steps, owner |
+| `standard` | Guidelines, conventions | name, category, guidelines |
+| `template` | Reusable templates | name, category, template_content |
+| `reference` | Articles, research, bookmarks | name, type, source, link |
+| `technique` | Methods, frameworks | name, category, difficulty |
+| `practice-area` | Service lines, capabilities | name, description, capabilities |
+| `case-study` | Portfolio work, showcases | title, client, year, practice_areas |
+
+### Common Obsidian Directory Mappings
+
+These are patterns seen across vaults — adapt to the actual vault:
+
+| Directory pattern | Likely entity type | Notes |
+|-------------------|--------------------|-------|
+| `Projects/` | `project` | May have sub-documents (see nested content below) |
+| `People/`, `Contacts/` | `person` | Usually flat files |
+| `Team/`, `Staff/` | `person` | Often richer frontmatter than external contacts |
+| `Clients/`, `Companies/`, `Organizations/` | `client` | May have subdirectories by relationship type |
+| `Meetings/`, `Meeting Notes/` | `meeting` | Date-prefixed filenames common |
+| `Tasks/`, `Action Items/` | `task` | May overlap with a task manager integration |
+| `SOPs/`, `Processes/`, `Workflows/` | `process` | Often has category/status/owner fields |
+| `Areas/`, `Practice Areas/`, `Capabilities/` | `practice-area` | May lack frontmatter |
+| `Case Studies/`, `Portfolio/`, `Work/` | `case-study` | Often has client, year, url fields |
+| `Research/`, `References/`, `Resources/` | `reference` | Bookmarks, articles, links |
+| `HR/`, `Roles/`, `Job Descriptions/` | `role` | Job postings, org structure |
+| `Finances/`, `Finance/`, `Budgets/` | `financial-plan` | Rate cards, P&L, budgets |
+| `Standards/`, `Guidelines/` | `standard` | Naming conventions, code standards |
+| `Templates/` | `template` | Reusable document templates |
+| `Proposals/`, `SOWs/` | `proposal` | Client proposals |
+| `Contracts/` | `contract` | Agreements, NDAs |
+| `Events/`, `Conferences/` | `meeting` | No dedicated event type — meeting is closest |
+| `Emails/` | `artifact` | No dedicated email type |
+| `Archive/` | same as active, disabled | Enable later if needed |
+
+### Directories to Skip
+
+- `.obsidian/` — Obsidian config
+- `.smart-env/` — Smart Connections plugin data
+- `Attachments/`, `Assets/`, `Media/` — binary files
+- `Templates/` — often just scaffolding, not real entities (evaluate per vault)
+- `Daily Notes/` — usually ephemeral, not entity-worthy
+- `Clippings/` — web clippings, low signal
+
+### Handling Nested Project Content
+
+When a `Projects/` directory has subfolders with multiple files per project, ALL files get classified as the mapping's entity type. Sub-documents (meeting agendas, SOWs, concepts) become project entities.
+
+**Options:**
+1. **Accept and review** — the `studiograph review` step lets users fix misclassifications before committing
+2. **Use `unstructured` mode** — the LLM can infer the correct entity type from content (slower, costs per file)
+3. **Co-locate sub-files** — if sub-documents reference their parent project in frontmatter (e.g., `related_projects: ["[[My Project]]"]`), add `co_locate: { parent_field: "related_projects", subfolder: "notes" }` to write them as sub-content
+
+## Step 4: Choose Extraction Mode Per Mapping
+
+| Condition | Mode | Cost |
+|-----------|------|------|
+| Files have YAML frontmatter with useful fields | `frontmatter` | Free (no LLM) |
+| Files are plain markdown, no frontmatter | `unstructured` | LLM call per file |
+| Mix of both | `frontmatter` | Free — files without frontmatter are skipped |
+| Small directory (<20 files) with no frontmatter | `unstructured` | Acceptable LLM cost |
+| Large directory (100+) with no frontmatter | `frontmatter` or skip | `unstructured` would be expensive |
+
+## Step 5: Build Field Maps
+
+For each `frontmatter` mapping, build a `field_map` from the sampled YAML fields.
+
+**Rules:**
+- Keys are the Obsidian frontmatter field names (as they appear in the YAML)
+- Values are the Studiograph entity field names (from the entity type reference above)
+- Only map fields that actually exist in the frontmatter — don't invent mappings
+- Wikilink fields (`"[[Entity Name]]"`) map naturally — the sync pipeline handles them
+- Always include `tags` if the vault uses tags
+- Use `id_from: "_filename"` and `content_from: "_body"` for all Obsidian mappings
+
+**Common Obsidian frontmatter fields and their typical targets:**
+
+| Obsidian field | Target field | Notes |
+|----------------|-------------|-------|
+| `title` / `name` | `name` or `title` | Entity display name |
+| `status` | `status` | Map values with `status_map` if conventions differ |
+| `client` | `client` | Often a wikilink |
+| `date` | `date` | ISO date |
+| `start_date` / `end_date` | `start_date` / `end_date` | Date range |
+| `tags` | `tags` | Array of strings |
+| `email` | `email` | |
+| `role` / `title` (on person) | `role` | Obsidian often uses `title` for role |
+| `related_people` | `contacts` or `attendees` | Usually wikilink array |
+| `related_organizations` | `related_organizations` | Usually wikilink array |
+| `related_projects` | `related_projects` | Usually wikilink array |
+| `related_areas` | `related_areas` | Usually wikilink array |
+| `url` / `website` | `website_url` or `link` | |
+| `sectors` | `sectors` | Industry/domain tags |
+| `practice_areas` | `practice_areas` | Service line references |
+| `year` | `year` | For case studies |
+
+## Step 6: Determine Target Repos
+
+Check which repos exist in the workspace (`ls` the workspace directory or use `graph_list_repos`). Map entity types to existing repos:
+
+| Entity types | Typical repo |
+|-------------|-------------|
+| project, case-study, deliverable, brief, artifact | `projects` |
+| person, role | `people` |
+| client, vendor | `clients` |
+| meeting | `meetings` |
+| process, standard, template, reference, technique, practice-area | A shared-resource repo if one exists, otherwise `projects` |
+| deal, proposal, contract, financial-plan | A function repo if one exists, otherwise `projects` |
+
+If a needed repo doesn't exist, the sync pipeline auto-creates it on `sync_apply`.
+
+## Step 7: Write the Config
+
+Generate `.studiograph/sources/obsidian.json` with all mappings. Present it to the user for review before writing.
+
+**Template:**
+```json
+{
+  "name": "obsidian-<vault-name>",
+  "connector": "obsidian-<vault-name>",
+  "enabled": true,
+  "added_at": "<ISO timestamp>",
+  "entity_mappings": [
+    {
+      "source_type": "<descriptive-name>",
+      "entity_type": "<studiograph-type>",
+      "target_repo": "<repo-name>",
+      "extraction_mode": "frontmatter",
+      "enabled": true,
+      "directory_patterns": ["<VaultDir>/"],
+      "list_tool": "list_vault_files",
+      "read_tool": "get_vault_file",
+      "field_map": { ... },
+      "id_from": "_filename",
+      "content_from": "_body"
+    }
+  ]
+}
+```
+
+**Checklist before writing:**
+- [ ] Every content directory has a mapping (or a reason to skip)
+- [ ] `directory_patterns` use trailing slash and match the vault's exact directory names (case-sensitive)
+- [ ] `list_tool` and `read_tool` are set to `"list_vault_files"` and `"get_vault_file"` for Obsidian
+- [ ] Field maps only reference frontmatter fields that actually exist
+- [ ] Directories with no frontmatter use `unstructured` mode or are skipped
+- [ ] Subdirectories are handled (e.g., `Organizations/Clients/` not just `Organizations/`)
+- [ ] `target_repo` values match existing repos or the user is aware new ones will be created
+- [ ] Disabled mappings are marked `enabled: false` with a comment-like `source_type` explaining why
+
+## Multiple Vaults
+
+Each vault needs its own connector and source config. The MCP Tools binary is vault-specific — it connects to the Local REST API instance running in its vault.
+
+1. Install both plugins (Local REST API + MCP Tools) in each vault
+2. Create a connector per vault at `~/.studiograph/connectors/obsidian-<name>.json`, each pointing to that vault's `mcp-server` binary and API key
+3. Create a source config per vault at `.studiograph/sources/obsidian-<name>.json` with directory patterns matching that vault's structure
+4. Run `studiograph sync` (no arguments) to sync all enabled sources in one pass
+
+**Port conflict:** Each vault's Local REST API runs on port 27124 by default. Only one vault can use a given port at a time. If both vaults need to be open simultaneously, change the port in one vault's Local REST API settings.
+
+See `docs/obsidian-setup.md` for full connector setup and troubleshooting.
+
+## After Setup
+
+1. **Dry run:** `sync_run({ sources: ["obsidian"], dryRun: true })` — verify extraction counts look right
+2. **Full run:** `sync_run({ sources: ["obsidian"] })` — extract to staging
+3. **Review:** `sync_status` then `studiograph review` — spot-check entity types and field values
+4. **Apply:** `sync_apply` — write entity files
+5. **Commit:** `studiograph commit` — git commit across repos
+
+See the `sync-setup` skill for the full sync workflow and the `sync-configuration` skill for field map syntax details.

package/dist/agent/skills/sync-configuration.md

@@ -0,0 +1,144 @@
+---
+name: sync-configuration
+description: Reference for building sync source configs — field maps, transforms, co-location, extraction modes
+loading: eager
+---
+
+# Sync Configuration Reference
+
+Use this reference when helping users build or modify source configs at `.studiograph/sources/<name>.json`.
+
+## Source Config Structure
+
+```json
+{
+  "name": "linear",
+  "connector": "linear",
+  "enabled": true,
+  "added_at": "2026-02-15T10:00:00.000Z",
+  "entity_mappings": [ ... ],
+  "field_priority": { "email": "pipedrive" }
+}
+```
+
+- `connector` references a connector in `~/.studiograph/connectors/`
+- `field_priority` — optional per-field merge priority when multiple sources write the same entity
+- `entity_mappings` — array of mappings, each maps one external entity type to a Studiograph type
+
+## Entity Mapping Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `source_type` | Yes | What the source calls this type (e.g. `"deal"`, `"issue"`) |
+| `entity_type` | Yes | Studiograph type (e.g. `"project"`, `"task"`, `"meeting"`) |
+| `target_repo` | Yes | Repo to write to (e.g. `"projects"`) |
+| `extraction_mode` | Yes | `"structured"`, `"frontmatter"`, or `"unstructured"` |
+| `id_from` | No | Source field for entity_id (default `"title"`, or `"_filename"` for frontmatter mode) |
+| `content_from` | No | Source field for markdown body (or `"_body"` for frontmatter mode) |
+| `field_map` | No | Maps source fields to entity fields (see Field Map Syntax) |
+| `status_map` | No | Maps source status values to entity statuses (case-insensitive) |
+| `fetch_details` | No | Fetch full record per listed ID (for sparse list APIs) |
+| `list_limit` | No | Override limit param for list tool |
+| `list_params` | No | Extra params for list tool. Pass array for multiple list calls merged |
+| `directory_patterns` | No | Directory patterns for file sources (frontmatter/unstructured) |
+| `write_mode` | No | `"entity"` (default, `id/main.md` folder) or `"collection"` (flat `id.md` file) |
+| `co_locate` | No | Co-locate as sub-content inside parent entity folder |
+| `list_tool` | No | Explicit MCP tool name for listing records (bypasses heuristic matching) |
+| `read_tool` | No | Explicit MCP tool name for reading records (bypasses heuristic matching) |
+
+## Extraction Modes
+
+- **`structured`** — API JSON → field_map → frontmatter. No LLM. For Pipedrive, Linear, Granola, Asana.
+- **`frontmatter`** — Markdown files with YAML → field_map. No LLM. For Obsidian. Supports `_filename` and `_body` sentinels.
+- **`unstructured`** — Freeform text → LLM extraction. Slow, expensive. Last resort when no structured metadata exists.
+
+## Field Map Syntax
+
+Keys are source field paths, values are entity field names or FieldTransform objects.
+
+**Simple string:** `"title": "name"` — direct copy
+**Dot-notation:** `"org_id.name": "organization"` — nested access
+**Array index:** `"email[0].value": "email"` — specific array element
+**FieldTransform object:**
+```json
+{ "org_name": { "field": "client", "transform": "wikilink" } }
+```
+FieldTransform fields: `field` (target name), `transform` (transform type), `subfield` (optional — extract nested path from each array element before transforming)
+
+### Subfield example
+Source returns: `[{ "details": { "person": { "name": "Alice" } } }, ...]`
+Config: `{ "field": "attendees", "transform": "wikilink-array", "subfield": "details.person.name" }`
+Result: `["[[alice]]", ...]`
+
+## Transforms
+
+| Transform | Input | Output |
+|-----------|-------|--------|
+| `direct` | `"hello"` | `"hello"` (passthrough) |
+| `kebab-case` | `"Acme Corp"` | `"acme-corp"` |
+| `date-iso` | `"2026-02-20T14:30:00Z"` | `"2026-02-20"` |
+| `wikilink` | `"Acme Corp"` | `"[[acme-corp]]"` |
+| `wikilink-array` | `["Alice", "Bob"]` | `["[[alice]]", "[[bob]]"]` |
+
+## Co-Location
+
+Writes entities as sub-content files inside a parent entity folder instead of standalone entity folders.
+
+**Config:** Add `co_locate` to a mapping:
+```json
+{
+  "co_locate": { "parent_field": "project", "subfolder": "tasks" },
+  "field_map": { "project": { "field": "project", "transform": "wikilink" } }
+}
+```
+
+**Result path:** `{target_repo}/{parent_id}/{subfolder}/{entity_id}.md`
+Example: `projects/cooper-hewitt-brand-refresh/tasks/sch-101.md`
+
+**Rules:**
+- `parent_field` must be a wikilink target in `field_map` so the reference is available
+- Entities without a parent value are **skipped** (not an error)
+- Co-located files are sub-content, not graph entities (no `entity_id/main.md` folder)
+- `target_repo` should be the repo where the **parent** entities live
+
+## Write Mode
+
+Controls how entities are written to disk:
+
+- **`entity`** (default) — `repo/entity-id/main.md` folder. Fully indexed, supports sub-content. Use for core types (projects, clients, people).
+- **`collection`** — `repo/entity-id.md` flat file. Simpler, no folder overhead. Use for high-volume types (meetings, notes, references).
+
+## Explicit MCP Tool Selection
+
+For file-based sources (frontmatter, unstructured), add `list_tool` and `read_tool` when the connector's tool names don't follow predictable patterns:
+```json
+{ "list_tool": "list_vault_files", "read_tool": "get_vault_file" }
+```
+When omitted, the pipeline uses heuristic matching (looking for tools containing "list", "read", "get", etc.).
+
+## Sentinels (frontmatter mode only)
+
+- `_filename` in `id_from` — entity ID from the file's name (slugified, `.md` stripped)
+- `_body` in `content_from` — markdown body from file content below the `---` frontmatter fence
+
+## Built-in Definitions
+
+| Source | Mappings | Notes |
+|--------|----------|-------|
+| **Pipedrive** | deal→project, person→person, org→client | Ready to sync |
+| **Granola** | document→meeting | `fetch_details: true`, `list_limit: 1000` |
+| **Linear** | issue→task (co-located under projects), project→project | Issues use `co_locate` |
+| **Asana** | task→task, project→project | Needs `list_params: { workspace: "GID" }` |
+| **Obsidian** | Example mappings only (`.template` file) | Needs customization per vault |
+
+## Configuration Patterns
+
+**Adding co-location to any mapping:** Add `co_locate: { parent_field, subfolder }` and ensure `parent_field` is a wikilink target in `field_map`.
+
+**Multiple list calls:** Set `list_params` as an array: `[{ workspace: "123", archived: false }, { workspace: "123", archived: true }]`
+
+**Custom source (no built-in):** Create a source config with `entity_mappings` from scratch. Choose extraction_mode, define field_map targeting entity schema fields, set target_repo.
+
+**Overriding built-in defaults:** Pass custom `entity_mappings` to `sync_setup_source` — they replace the defaults entirely. Or edit `.studiograph/sources/<name>.json` directly.
+
+**Status maps:** Map source status strings (case-insensitive) to Studiograph enums. Common patterns: Pipedrive (`won→completed, lost→archived, open→active`), Linear issues (`Backlog→open, In Progress→in-progress, Done→done, Canceled→cancelled`).

package/dist/agent/skills/sync-setup.md

@@ -0,0 +1,84 @@
+---
+name: sync-setup
+description: Guide for setting up and running entity sync from external sources
+loading: eager
+---
+
+# Entity Sync
+
+You can sync data from external sources (Linear, Pipedrive, Granola, Obsidian, etc.) into the knowledge graph using the sync tools.
+
+## First-Time Setup
+
+1. **Check what's available:** Call `sync_list_sources` immediately — it returns configured sources (with full entity_mappings), available connectors, and known source definitions
+2. **Verify the connector exists** — connectors hold API credentials and are CLI-only for security. If missing, tell the user:
+   > "You'll need to set up the connector first. Run `studiograph connector add <name>` in your terminal."
+3. **Add the source:** `sync_setup_source({ name: "linear" })` — uses default mappings from built-in definitions when available
+4. **Customize if needed:** Built-in definitions (Pipedrive, Granola, Linear, Asana) provide ready-to-use defaults. To customize, pass `entity_mappings` to `sync_setup_source` to override field maps, add co-location, change target repos, or add status maps. See the `sync-configuration` skill for field map syntax and options.
+5. **No built-in definition?** Use `sync_inspect_connector` to discover the connector's tools and syncable entity types, then `sync_sample_data` to fetch a sample record and see field shapes. Build `entity_mappings` from the field analysis. See below and the `sync-configuration` skill for the full mapping schema.
+6. **Run the sync:** `sync_run({ sources: ["linear"] })`
+7. **Review staging:** `sync_status` — show the user what will be committed
+8. **Apply on confirmation:** Only call `sync_apply` after the user approves
+9. **Review & commit:** `studiograph review` (interactive diff review with approve/reject per entity), then `studiograph commit` (git commit across all repos)
+
+## Building a Config from Scratch (no built-in definition)
+
+When a connector has no built-in source definition, use introspection to auto-discover the data model:
+
+1. `sync_inspect_connector({ connector: "myservice" })` — lists all tools categorized by purpose, detects syncable entity types with list/get tool pairs
+2. Pick which entity types to sync from the `syncableTypes` results
+3. `sync_sample_data({ connector: "myservice", tool: "list_records" })` — fetches one record and analyzes field shapes. Returns field paths, types, sample values, and suggested field_map entries
+4. Build `entity_mappings` using the field analysis — map source fields to entity schema fields using dot notation for nested fields
+5. `sync_setup_source({ name: "myservice", entity_mappings: [...] })` — save the config
+
+**Tips:**
+- `sync_sample_data` auto-sets `limit: 1` — you don't need to pass it
+- Use the `suggestedFieldMap` from the response as a starting point
+- Nested fields use dot notation in field_map keys (e.g. `"org_id.name": "organization"`)
+- Call `sync_sample_data` for each entity type you plan to sync
+
+## Modifying an Existing Source
+
+When a user asks to adjust, change, or view a source config, **immediately call `sync_list_sources`** to read the current configuration. Do not ask the user to paste the config — you can read it yourself.
+
+1. `sync_list_sources` — call this FIRST, before asking questions (returns full `entity_mappings` with field maps, transforms, etc.)
+2. Show the user the relevant parts of their config and ask what they want to change
+3. Build the updated `entity_mappings` array (you must pass the complete array — it replaces, not merges)
+4. `sync_setup_source({ name: "...", entity_mappings: [...], force: true })` — overwrite with updated config
+
+Common adjustments: changing `field_map` entries, adding/removing entity mappings, changing `target_repo`, adding `co_locate`, switching `write_mode`, adjusting `status_map`, adding `list_tool`/`read_tool`.
+
+## Repeat Sync Flow
+
+1. `sync_run({ incremental: true })` — only fetches records updated since last sync
+2. `sync_status` — present the summary
+3. Wait for user confirmation
+4. `sync_apply` — writes entity files (no git commit)
+5. `workspace_status` — show what files changed across repos
+6. `workspace_review` — show diffs (optionally filter by `entityType`)
+7. `workspace_commit({ messagePrefix: "sync" })` — git commits across repos (or let user run `studiograph commit`)
+
+## Post-Apply Results
+
+After `sync_apply`, explain what happened to the user:
+
+- **Standard entities** are written as: `{target_repo}/{entity_id}/main.md` (entity folder with sentinel file)
+- **Co-located entities** are written as: `{target_repo}/{parent_id}/{subfolder}/{entity_id}.md` (flat file inside parent folder). Co-located files are sub-content, not graph entities.
+- **Skipped entities** — when co-location is configured but the parent field is empty or missing, those entities are skipped (not an error)
+- **Auto-registered repos** — if a `target_repo` doesn't exist yet, it's automatically created and registered in the workspace
+
+## Troubleshooting
+
+- **"Uncommitted changes"** — sync requires a clean working tree. Tell the user to commit or stash changes first, or use `--force` to override
+- **"Connector not found"** — the connector isn't set up. User must run `studiograph connector add <name>` in terminal
+- **Entities skipped during apply** — for co-located entities, check that the `parent_field` has a value in the extracted frontmatter. Missing parent = skip.
+- **Obsidian template file** — Obsidian creates a `.template` file instead of default mappings (every vault is different). Tell the user to copy mappings from the template into the source config and adjust `directory_patterns` and `field_map` for their vault.
+
+## Important Rules
+
+- **Never auto-commit** — always show `sync_status` and get user confirmation before `sync_apply`
+- **Connector management is CLI-only** — API keys and tokens must be set up via `studiograph connector add/remove`. Never ask users to provide API keys in chat
+- **Use incremental for repeat syncs** — avoids re-processing unchanged records
+- **Use dry run for previews** — `sync_run({ dryRun: true })` shows what would be extracted without writing staging
+- **Abort if needed** — `sync_abort` clears staging if the user wants to start over
+- **sync_commit is deprecated** — use `sync_apply` then `workspace_commit` instead

package/dist/agent/tools/connector-tools.d.ts

@@ -0,0 +1,37 @@
+/**
+ * On-demand connector tools
+ *
+ * Instead of registering hundreds of individual MCP connector tools with the
+ * agent (which bloats every API call), this module provides two lightweight
+ * proxy tools:
+ *
+ *   connector_list  — discover available connectors and their tools
+ *   connector_call  — route a call to a specific connector tool
+ *
+ * The actual MCP tool wrappers are stored in a registry built from
+ * ConnectorManager.buildTools() output.
+ */
+export interface ConnectorToolEntry {
+    /** Namespaced name: "pipedrive__deals_search" */
+    name: string;
+    /** Local name within the connector: "deals_search" */
+    localName: string;
+    /** Connector name: "pipedrive" */
+    connector: string;
+    description: string;
+    parameters: any;
+    execute: (toolCallId: string, params: any) => Promise<any>;
+}
+export interface ConnectorRegistry {
+    connectors: Map<string, ConnectorToolEntry[]>;
+}
+/**
+ * Build a registry from ConnectorManager's wrapped tool objects.
+ * Parses the namespaced tool names (e.g. "pipedrive__deals_search")
+ * into connector → tool[] groupings.
+ */
+export declare function buildConnectorRegistry(tools: any[]): ConnectorRegistry;
+/**
+ * Create two proxy tools for on-demand connector access.
+ */
+export declare function createConnectorTools(registry: ConnectorRegistry): any[];

package/dist/agent/tools/connector-tools.js

@@ -0,0 +1,132 @@
+/**
+ * On-demand connector tools
+ *
+ * Instead of registering hundreds of individual MCP connector tools with the
+ * agent (which bloats every API call), this module provides two lightweight
+ * proxy tools:
+ *
+ *   connector_list  — discover available connectors and their tools
+ *   connector_call  — route a call to a specific connector tool
+ *
+ * The actual MCP tool wrappers are stored in a registry built from
+ * ConnectorManager.buildTools() output.
+ */
+/**
+ * Build a registry from ConnectorManager's wrapped tool objects.
+ * Parses the namespaced tool names (e.g. "pipedrive__deals_search")
+ * into connector → tool[] groupings.
+ */
+export function buildConnectorRegistry(tools) {
+    const connectors = new Map();
+    for (const tool of tools) {
+        const sep = tool.name.indexOf('__');
+        const connector = sep !== -1 ? tool.name.slice(0, sep) : tool.name;
+        const localName = sep !== -1 ? tool.name.slice(sep + 2) : tool.name;
+        if (!connectors.has(connector))
+            connectors.set(connector, []);
+        connectors.get(connector).push({
+            name: tool.name,
+            localName,
+            connector,
+            description: tool.description ?? '',
+            parameters: tool.parameters,
+            execute: tool.execute,
+        });
+    }
+    return { connectors };
+}
+/**
+ * Create two proxy tools for on-demand connector access.
+ */
+export function createConnectorTools(registry) {
+    return [
+        {
+            name: 'connector_list',
+            description: 'List available external connectors and their tools. Call with no arguments to see all connectors, or with connector name to see its tools, or with both connector and tool to see a tool\'s parameter schema.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    connector: {
+                        type: 'string',
+                        description: 'Show tools for this connector (e.g. "pipedrive", "linear")',
+                    },
+                    tool: {
+                        type: 'string',
+                        description: 'Show the parameter schema for this specific tool',
+                    },
+                },
+            },
+            execute: async (_toolCallId, params) => {
+                // Specific tool schema
+                if (params.connector && params.tool) {
+                    const tools = registry.connectors.get(params.connector);
+                    if (!tools) {
+                        return { content: [{ type: 'text', text: `Connector "${params.connector}" not found. Available: ${[...registry.connectors.keys()].join(', ')}` }] };
+                    }
+                    const tool = tools.find(t => t.localName === params.tool);
+                    if (!tool) {
+                        return { content: [{ type: 'text', text: `Tool "${params.tool}" not found in ${params.connector}.` }] };
+                    }
+                    return { content: [{ type: 'text', text: `${params.connector} / ${params.tool}\n${tool.description}\n\nParameters:\n${JSON.stringify(tool.parameters, null, 2)}` }] };
+                }
+                // Tools for a specific connector
+                if (params.connector) {
+                    const tools = registry.connectors.get(params.connector);
+                    if (!tools) {
+                        return { content: [{ type: 'text', text: `Connector "${params.connector}" not found. Available: ${[...registry.connectors.keys()].join(', ')}` }] };
+                    }
+                    const list = tools.map(t => `- ${t.localName}: ${t.description}`).join('\n');
+                    return { content: [{ type: 'text', text: `${params.connector} (${tools.length} tools):\n${list}` }] };
+                }
+                // All connectors overview
+                const summary = [...registry.connectors.entries()]
+                    .map(([name, tools]) => `- ${name} (${tools.length} tools)`)
+                    .join('\n');
+                return { content: [{ type: 'text', text: `Available connectors:\n${summary}\n\nCall with connector to see available tools.` }] };
+            },
+        },
+        {
+            name: 'connector_call',
+            description: 'Call a tool on an external service (Pipedrive, Linear, Granola, Asana, Obsidian). Use connector_list first to discover available tools and their parameters.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    connector: {
+                        type: 'string',
+                        description: 'Connector name (e.g. "pipedrive", "linear", "granola")',
+                    },
+                    tool: {
+                        type: 'string',
+                        description: 'Tool name within the connector (e.g. "deals_search", "list_issues")',
+                    },
+                    arguments: {
+                        type: 'object',
+                        description: 'Arguments to pass to the tool',
+                        additionalProperties: true,
+                    },
+                },
+                required: ['connector', 'tool'],
+            },
+            execute: async (_toolCallId, params) => {
+                const tools = registry.connectors.get(params.connector);
+                if (!tools) {
+                    return {
+                        content: [{ type: 'text', text: `Connector "${params.connector}" not found. Available: ${[...registry.connectors.keys()].join(', ')}` }],
+                        isError: true,
+                    };
+                }
+                const tool = tools.find(t => t.localName === params.tool);
+                if (!tool) {
+                    const available = tools.slice(0, 20).map(t => t.localName).join(', ');
+                    const suffix = tools.length > 20 ? ` ... and ${tools.length - 20} more` : '';
+                    return {
+                        content: [{ type: 'text', text: `Tool "${params.tool}" not found in ${params.connector}. Available: ${available}${suffix}` }],
+                        isError: true,
+                    };
+                }
+                return tool.execute(_toolCallId, params.arguments || {});
+            },
+        },
+    ];
+}
+//# sourceMappingURL=connector-tools.js.map

package/dist/agent/tools/connector-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector-tools.js","sourceRoot":"","sources":["../../../src/agent/tools/connector-tools.ts"],"names":[],"mappings":"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"}