studiograph 1.1.2 → 1.2.0-beta.1

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/skill-loader.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Skill Loader — prompt skills for the Studiograph agent.
+ *
+ * Skills are markdown files with YAML frontmatter that inject domain-specific
+ * knowledge into the agent's system prompt. Two formats supported:
+ *
+ *   Directory skill:
+ *     skills/create-deck/
+ *       skill.md        ← required entrypoint
+ *       slide-types.md  ← optional sub-files
+ *
+ *   Single-file skill:
+ *     skills/quick-tip.md
+ *
+ * Frontmatter fields:
+ *   name:        kebab-case identifier (defaults to directory/filename)
+ *   description: shown in skill index so agent knows when to load it
+ *   loading:     "on-demand" (default) | "eager" (inlined in system prompt)
+ */
+export interface SkillMeta {
+    name: string;
+    description: string;
+    loading: 'eager' | 'on-demand';
+    dir: string;
+    entrypoint: string;
+    isDirectory: boolean;
+}
+/**
+ * Scan one or more skill directories and return a de-duplicated skill index.
+ * Directories are processed in order — first occurrence of a name wins,
+ * so workspace-level skills override app-bundled skills.
+ */
+export declare function loadSkillIndex(skillsDirs: string[]): SkillMeta[];
+/**
+ * Load the full content of a skill's entrypoint or a named sub-file.
+ * Sanitises the file parameter to prevent path traversal.
+ */
+export declare function loadSkillContent(meta: SkillMeta, file?: string): string;
+/**
+ * Build the skill index section to append to the system prompt.
+ * Eager skills are inlined separately; this lists only on-demand skills.
+ */
+export declare function buildSkillIndexPrompt(skills: SkillMeta[]): string;
+/**
+ * Return the full content of all eager skills, to be injected directly
+ * into the system prompt at startup.
+ */
+export declare function loadEagerSkills(skills: SkillMeta[]): string;

package/dist/agent/skills/skill-loader.js

@@ -0,0 +1,166 @@
+/**
+ * Skill Loader — prompt skills for the Studiograph agent.
+ *
+ * Skills are markdown files with YAML frontmatter that inject domain-specific
+ * knowledge into the agent's system prompt. Two formats supported:
+ *
+ *   Directory skill:
+ *     skills/create-deck/
+ *       skill.md        ← required entrypoint
+ *       slide-types.md  ← optional sub-files
+ *
+ *   Single-file skill:
+ *     skills/quick-tip.md
+ *
+ * Frontmatter fields:
+ *   name:        kebab-case identifier (defaults to directory/filename)
+ *   description: shown in skill index so agent knows when to load it
+ *   loading:     "on-demand" (default) | "eager" (inlined in system prompt)
+ */
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { join, extname, basename } from 'path';
+/**
+ * Minimal YAML frontmatter parser — handles the subset used by skills.
+ */
+function parseFrontmatter(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!match) {
+        return { meta: {}, body: content };
+    }
+    const meta = {};
+    for (const line of match[1].split('\n')) {
+        const colon = line.indexOf(':');
+        if (colon === -1)
+            continue;
+        const key = line.slice(0, colon).trim();
+        const value = line.slice(colon + 1).trim();
+        if (key)
+            meta[key] = value;
+    }
+    return { meta, body: match[2] };
+}
+/**
+ * Scan one or more skill directories and return a de-duplicated skill index.
+ * Directories are processed in order — first occurrence of a name wins,
+ * so workspace-level skills override app-bundled skills.
+ */
+export function loadSkillIndex(skillsDirs) {
+    const skills = [];
+    const seen = new Set();
+    for (const dir of skillsDirs) {
+        if (!existsSync(dir))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.startsWith('.'))
+                continue;
+            const entryPath = join(dir, entry);
+            // Directory skill: subdirectory containing skill.md
+            const skillMd = join(entryPath, 'skill.md');
+            if (existsSync(skillMd)) {
+                try {
+                    const content = readFileSync(skillMd, 'utf-8');
+                    const { meta } = parseFrontmatter(content);
+                    const name = meta.name || entry;
+                    if (!seen.has(name)) {
+                        seen.add(name);
+                        skills.push({
+                            name,
+                            description: meta.description || '',
+                            loading: meta.loading === 'eager' ? 'eager' : 'on-demand',
+                            dir: entryPath,
+                            entrypoint: skillMd,
+                            isDirectory: true,
+                        });
+                    }
+                }
+                catch {
+                    // skip malformed skill
+                }
+                continue;
+            }
+            // Single-file skill: top-level .md file with valid frontmatter
+            if (extname(entry) === '.md') {
+                try {
+                    const content = readFileSync(entryPath, 'utf-8');
+                    const { meta } = parseFrontmatter(content);
+                    // Must have at least name or description to be a skill
+                    if (!meta.name && !meta.description)
+                        continue;
+                    const name = meta.name || basename(entry, '.md');
+                    if (!seen.has(name)) {
+                        seen.add(name);
+                        skills.push({
+                            name,
+                            description: meta.description || '',
+                            loading: meta.loading === 'eager' ? 'eager' : 'on-demand',
+                            dir,
+                            entrypoint: entryPath,
+                            isDirectory: false,
+                        });
+                    }
+                }
+                catch {
+                    // skip
+                }
+            }
+        }
+    }
+    return skills;
+}
+/**
+ * Load the full content of a skill's entrypoint or a named sub-file.
+ * Sanitises the file parameter to prevent path traversal.
+ */
+export function loadSkillContent(meta, file) {
+    if (file) {
+        if (!meta.isDirectory) {
+            return `Error: skill "${meta.name}" is a single-file skill with no sub-files.`;
+        }
+        // Allow only simple filenames — no slashes, no dots at start
+        const safeName = file.replace(/[^a-zA-Z0-9._-]/g, '');
+        if (!safeName || safeName.startsWith('.')) {
+            return `Error: invalid sub-file name "${file}".`;
+        }
+        const filePath = join(meta.dir, safeName);
+        if (!existsSync(filePath)) {
+            return `Error: sub-file "${safeName}" not found in skill "${meta.name}".`;
+        }
+        return readFileSync(filePath, 'utf-8');
+    }
+    return readFileSync(meta.entrypoint, 'utf-8');
+}
+/**
+ * Build the skill index section to append to the system prompt.
+ * Eager skills are inlined separately; this lists only on-demand skills.
+ */
+export function buildSkillIndexPrompt(skills) {
+    const onDemand = skills.filter(s => s.loading === 'on-demand');
+    if (onDemand.length === 0)
+        return '';
+    const lines = [
+        '## Available Skills',
+        '',
+        'Call `load_skill` to load domain-specific guidance when it is relevant to the current task.',
+        '',
+        ...onDemand.map(s => `- **${s.name}** — ${s.description}`),
+    ];
+    return lines.join('\n');
+}
+/**
+ * Return the full content of all eager skills, to be injected directly
+ * into the system prompt at startup.
+ */
+export function loadEagerSkills(skills) {
+    return skills
+        .filter(s => s.loading === 'eager')
+        .map(s => loadSkillContent(s))
+        .join('\n\n---\n\n');
+}
+//# sourceMappingURL=skill-loader.js.map

package/dist/agent/skills/skill-loader.js.map

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

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`).