studiograph 1.1.3 → 1.2.0-beta.2

package/README.md

@@ -22,7 +22,7 @@ npm install -g studiograph
 studiograph init "My Studio"
 ```
 
-The interactive setup will ask you to choose a firm template (design studio, marketing agency, architecture studio, etc.) or start bare. This creates a workspace directory with a `.studiograph/` config folder — similar to how Git uses `.git/`.
+This creates a workspace directory with a `.studiograph/` config folder — similar to how Git uses `.git/` — and scaffolds example entities to get you started.
 
 To create repos on GitHub during init:
 
@@ -30,13 +30,6 @@ To create repos on GitHub during init:
 studiograph init "My Studio" --github --github-org my-org
 ```
 
-To skip the interactive template picker:
-
-```bash
-studiograph init "My Studio" --template design-studio
-studiograph init "My Studio" --bare
-```
-
 ### Join an Existing Workspace
 
 ```bash
@@ -166,6 +159,7 @@ There are 30+ built-in entity types (project, meeting, client, deliverable, prop
 | `studiograph connector` | Configure third-party integrations (Linear, Slack, Figma, etc.) |
 | `studiograph app` | Manage installed app plugins |
 | `studiograph r2` | Configure Cloudflare R2 for asset storage |
+| `studiograph source` | Manage sync sources for entity extraction ([configuration reference](docs/sync-configuration.md)) |
 
 ## Integrations
 

package/dist/agent/orchestrator.js

@@ -14,10 +14,13 @@ import { getModel } from '@mariozechner/pi-ai';
 import { Agent } from '@mariozechner/pi-agent-core';
 import { WorkspaceManager } from '../core/workspace-manager.js';
 import { createGraphTools } from './tools/graph-tools.js';
-import { loadSkillIndex, buildSkillIndexPrompt, loadEagerSkills } from './skills/skill-loader.js';
+import { createSyncTools } from './tools/sync-tools.js';
+import { loadSkillIndex, buildSkillIndexPrompt, loadEagerSkills } from './skill-loader.js';
 import { createLoadSkillTool } from './tools/load-skill.js';
 import { loadCustomTools } from './tools/tool-loader.js';
 import { ConnectorManager } from '../mcp/connector-manager.js';
+import { buildConnectorRegistry, createConnectorTools } from './tools/connector-tools.js';
+import { createFsTools } from './tools/fs-tools.js';
 import { loadUserConfig, getAnthropicCredential } from '../core/user-config.js';
 export class AgentOrchestrator {
     workspacePath;
@@ -37,7 +40,7 @@ export class AgentOrchestrator {
         const userToolsDir = join(homedir(), '.studiograph', 'tools');
         const workspaceSkillsDir = join(this.workspacePath, '.studiograph', 'skills');
         const workspaceToolsDir = join(this.workspacePath, '.studiograph', 'tools');
-        const bundledSkillsDir = join(__dirname, 'skills', 'bundled');
+        const bundledSkillsDir = join(__dirname, 'skills');
         this.skillsDirs = [userSkillsDir, workspaceSkillsDir, bundledSkillsDir, ...(config.skillsDirs ?? [])];
         this.toolsDirs = [userToolsDir, workspaceToolsDir, ...(config.toolsDirs ?? [])];
         // Initialize workspace manager
@@ -51,9 +54,9 @@ export class AgentOrchestrator {
      * Custom tools and skills are loaded asynchronously via initAsync().
      */
     createAgent() {
-        const provider = this.config.model_provider || 'anthropic';
-        const modelId = this.config.model_id || 'claude-sonnet-4-5-20250929';
         const userConfig = loadUserConfig();
+        const provider = userConfig.model_provider || this.config.model_provider || 'anthropic';
+        const modelId = userConfig.model_id || this.config.model_id || 'claude-sonnet-4-5-20250929';
         const apiKey = getAnthropicCredential(userConfig) || this.config.api_key || process.env.ANTHROPIC_API_KEY || '';
         if (!apiKey) {
             throw new Error('API key not found in config or environment');
@@ -61,13 +64,17 @@ export class AgentOrchestrator {
         const model = getModel(provider, modelId);
         // Build skill index (synchronous — reads markdown frontmatter only)
         const skillIndex = loadSkillIndex(this.skillsDirs);
-        // Build system prompt — base + eager skills + skill index
-        const systemPrompt = this.buildSystemPrompt(skillIndex);
-        // Built-in graph tools + load_skill tool
+        // Build tools first so we can auto-generate the tool reference for the prompt
         const tools = [
-            ...createGraphTools(this.workspaceManager, this.gitUser),
+            ...createGraphTools(this.workspaceManager, this.gitUser, this.workspacePath),
+            ...createSyncTools(this.workspacePath, this.config),
+            ...createFsTools(),
             createLoadSkillTool(skillIndex),
         ];
+        // Build system prompt — base + auto-generated tool reference + eager skills + skill index
+        const systemPrompt = this.buildSystemPrompt(skillIndex, tools);
+        // Log registered tools at startup
+        console.log(`🔧 ${tools.length} tools registered: ${tools.map((t) => t.name).join(', ')}`);
         const agent = new Agent({ getApiKey: () => apiKey });
         agent.setModel(model);
         agent.setSystemPrompt(systemPrompt);
@@ -88,7 +95,11 @@ export class AgentOrchestrator {
             loadCustomTools(this.toolsDirs, context),
             ConnectorManager.buildTools(ConnectorManager.loadConfigs()),
         ]).then(([customTools, connectorTools]) => {
-            const extra = [...customTools, ...connectorTools];
+            const extra = [...customTools];
+            if (connectorTools.length > 0) {
+                const registry = buildConnectorRegistry(connectorTools);
+                extra.push(...createConnectorTools(registry));
+            }
             if (extra.length > 0) {
                 const existing = agent.state.tools;
                 agent.setTools([...existing, ...extra]);
@@ -100,11 +111,45 @@ export class AgentOrchestrator {
     /**
      * Build the full system prompt: base prompt + eager skill content + skill index.
      */
-    buildSystemPrompt(skillIndex) {
+    buildSystemPrompt(skillIndex, tools) {
         const promptPath = join(__dirname, 'prompts', 'system.md');
-        const base = existsSync(promptPath)
+        let base = existsSync(promptPath)
             ? readFileSync(promptPath, 'utf-8')
             : this.getDefaultSystemPrompt();
+        // Auto-generate tool reference from registered tools, grouped by category
+        const categories = {
+            'Entity Management': [],
+            'Data Sync & Source Config': [],
+            'Enrichment': [],
+            'Workspace Git': [],
+            'External Connectors': [],
+            'Skills': [],
+            'Other': [],
+        };
+        for (const t of tools) {
+            if (t.description?.startsWith('DEPRECATED'))
+                continue;
+            const name = t.name ?? '';
+            if (name.startsWith('sync_'))
+                categories['Data Sync & Source Config'].push(t);
+            else if (name.startsWith('enrich_'))
+                categories['Enrichment'].push(t);
+            else if (name.startsWith('workspace_'))
+                categories['Workspace Git'].push(t);
+            else if (name.startsWith('connector_'))
+                categories['External Connectors'].push(t);
+            else if (name === 'load_skill')
+                categories['Skills'].push(t);
+            else if (['create_entity', 'get_entity', 'update_entity', 'delete_entity', 'search_entities', 'list_entities', 'get_related', 'get_backlinks', 'validate_wikilinks', 'get_workspace_summary', 'list_repos', 'query_dataset', 'append_rows', 'get_entity_schema', 'lint_entities'].includes(name))
+                categories['Entity Management'].push(t);
+            else
+                categories['Other'].push(t);
+        }
+        const toolRef = Object.entries(categories)
+            .filter(([, items]) => items.length > 0)
+            .map(([cat, items]) => `**${cat}:**\n${items.map((t) => `- \`${t.name}\` — ${t.description}`).join('\n')}`)
+            .join('\n\n');
+        base = base.replace('{{TOOL_REFERENCE}}', toolRef);
         const parts = [base.trim()];
         // Append workspace schema extensions (org-specific fields and custom types)
         const schemaSection = this.workspaceManager.getSchemaRegistry().toPromptSection();

package/dist/agent/orchestrator.js.map

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

package/dist/agent/prompts/system.md

@@ -29,8 +29,9 @@ You can help users with:
 
 ## Guidelines
 
-**Be Conversational:**
-- Ask clarifying questions before taking action
+**Be Action-Oriented:**
+- When you have a tool that can answer a question, call it first — then discuss results
+- Don't ask users to provide information you can look up yourself (e.g. source configs, workspace status, entity data)
 - Explain what you're doing and why
 - Suggest next steps proactively
 
@@ -149,15 +150,32 @@ When a user says "make it private", "keep this to myself", "don't share this", o
 
 ## Tools
 
-You have access to graph management tools that allow you to:
-- Create, read, update, delete entities
-- Search and filter entities across repos
-- Manage wikilinks and relationships
-- Upload and manage assets
-- Get workspace statistics
-- Query dataset rows with filters (`query_dataset`) and append new rows (`append_rows`)
+You have access to tools in the following categories:
 
-Use these tools to help users build and navigate their knowledge graph effectively.
+**Entity Management** — CRUD operations on knowledge graph entities, wikilink traversal, search, schema queries, datasets, and linting.
+
+**Data Sync** — Import data from external sources (Pipedrive, Linear, Granola, Obsidian, etc.) through the sync pipeline: extract → reconcile → stage → apply.
+
+**Enrichment** — LLM-powered enrichment of sparse entities using cross-source context.
+
+**Workspace Git** — Check uncommitted changes, review diffs, and commit across all workspace repos. Use these when users ask about pending changes or want to commit.
+
+**Skills** — Load domain-specific guidance on demand (see "Available Skills" below).
+
+### Tool Selection
+
+**IMPORTANT — match user intent to the right tool category:**
+- "source config", "sync config", "field map", "mappings" → `sync_list_sources` (NOT entity search)
+- "uncommitted changes", "what changed", "pending changes" → `workspace_status`
+- "show diff", "review changes" → `workspace_review`
+- "commit", "save changes" → `workspace_commit`
+- Source configs are NOT entities — they live in `.studiograph/sources/` and are accessed via sync tools, not entity tools.
+
+### Tool Reference
+
+{{TOOL_REFERENCE}}
+
+Use these tools to help users build, navigate, and synchronize their knowledge graph effectively.
 
 ## Remember
 

package/dist/agent/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/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/skill-loader.js.map

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

package/dist/agent/skills/{bundled/enrich-entities.md → enrich-entities.md}

@@ -8,6 +8,18 @@ loading: eager
 
 When you discover incomplete entities (missing recommended fields), proactively suggest enrichment using contextual inference.
 
+## Batch Enrichment (automated)
+
+For bulk enrichment of entities with low completeness scores, use the `enrich_run` tool:
+
+1. `enrich_run({ dryRun: true })` — preview what would be enriched
+2. Present summary to user, get confirmation
+3. `enrich_run()` — run enrichment (writes in-place, no git commit)
+4. "Review changes with `studiograph review`, then commit with `studiograph commit`"
+5. `workspace_commit({ messagePrefix: "enrich" })` — or let user commit via CLI
+
+Use `enrich_abort` to discard all changes if the results aren't satisfactory.
+
 ## When to Enrich
 
 **Proactive discovery:**