vortexa-claude-skills 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## [1.0.0] - 2026-02-27
+
+### Initial Release
+
+**9 Skills:**
+- `/vortexa:init` -- Environment setup (API key, Python validation)
+- `/vortexa:cargo-flows` -- Cargo flow queries via CargoTimeSeries and CargoMovements
+- `/vortexa:breakdown` -- Dimensional breakdowns with stacked bar charts
+- `/vortexa:voyages` -- Vessel voyage queries via VoyagesSearchEnriched and VoyagesTimeseries
+- `/vortexa:custom` -- Open-ended Vortexa API queries and code improvement
+- `/vortexa:explain` -- Plain-English Vortexa data model explanations
+- `/vortexa:seasonal` -- Multi-year seasonal pattern analysis with min/max/avg bands
+- `/vortexa:oow` -- Oil-on-water breakdown by region (CM-Authoritative methodology)
+- `/vortexa:compare` -- Period-over-period and region-over-region comparison analytics
+
+**Foundation:**
+- 6 context documents covering Cargo Movements, Voyages, Reference Endpoints, guardrails, entity resolution, date/unit handling
+- 11 Python library modules with entity resolution, timeseries, movements, voyages, seasonal analysis, visualization
+- Vortexa dark Plotly theme with branded colour palette
+- Endpoint template pattern for adding new API endpoints
+
+**Distribution:**
+- One-command install: `npx @vortexa/claude-skills setup`
+- Per-directory init: `/vortexa:init` for environment setup
+- Cross-platform: Mac, Windows, Linux
+- Automatic update: `npx @vortexa/claude-skills update`

package/VERSION

@@ -0,0 +1 @@
+1.0.0

package/bin/setup.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+const packageDir = path.resolve(__dirname, '..');
+const version = fs.readFileSync(path.join(packageDir, 'VERSION'), 'utf8').trim();
+
+function getTargetDir() {
+  const home = os.homedir();
+  if (!home) {
+    console.error('Could not determine home directory. Set the HOME environment variable and try again.');
+    process.exit(1);
+  }
+  return path.join(home, '.claude');
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function hashFile(filepath) {
+  const content = fs.readFileSync(filepath);
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+function rewritePaths(content, targetDir) {
+  const vortexaDir = path.join(targetDir, 'vortexa');
+  const commandsDir = path.join(targetDir, 'commands', 'vortexa');
+
+  content = content.replace(/@context\//g, `@${vortexaDir}/context/`);
+  content = content.replace(/@commands\/vortexa\//g, `@${commandsDir}/`);
+
+  content = content.replace(/`context\//g, `\`${vortexaDir}/context/`);
+
+  content = content.replace(/sys\.path\.insert\(0,\s*"lib"\)/g,
+    'sys.path.insert(0, os.path.expanduser("~/.claude/vortexa"))');
+
+  content = content.replace(/`templates\//g, `\`${vortexaDir}/templates/`);
+
+  return content;
+}
+
+function copyDir(srcDir, destDir, options = {}) {
+  const { rewrite = false, targetDir = null } = options;
+  const installedFiles = [];
+
+  if (!fs.existsSync(srcDir)) return installedFiles;
+
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name.startsWith('.') && entry.name !== '.env.template') continue;
+    if (entry.name === '__pycache__') continue;
+
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      ensureDir(destPath);
+      const subFiles = copyDir(srcPath, destPath, options);
+      installedFiles.push(...subFiles);
+    } else {
+      let content = fs.readFileSync(srcPath);
+
+      if (rewrite && targetDir && entry.name.endsWith('.md')) {
+        content = rewritePaths(content.toString('utf8'), targetDir);
+        fs.writeFileSync(destPath, content, 'utf8');
+      } else {
+        fs.writeFileSync(destPath, content);
+      }
+
+      installedFiles.push(destPath);
+    }
+  }
+
+  return installedFiles;
+}
+
+function buildManifest(files, ver, targetDir) {
+  const fileHashes = {};
+  for (const filepath of files) {
+    const relative = path.relative(targetDir, filepath);
+    fileHashes[relative] = hashFile(filepath);
+  }
+
+  return {
+    version: ver,
+    installed_at: new Date().toISOString(),
+    file_count: files.length,
+    files: fileHashes
+  };
+}
+
+function readSettings(settingsPath) {
+  try {
+    return JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeSettings(settingsPath, settings) {
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+}
+
+function mergeSkillRegistrations(targetDir) {
+  const settingsPath = path.join(targetDir, 'settings.json');
+  const settings = readSettings(settingsPath);
+
+  if (!settings.customCommands) {
+    settings.customCommands = {};
+  }
+
+  const commandsDir = path.join(targetDir, 'commands', 'vortexa');
+  if (!fs.existsSync(commandsDir)) return;
+
+  const skills = fs.readdirSync(commandsDir)
+    .filter(f => f.endsWith('.md') && !f.startsWith('_'))
+    .map(f => {
+      const name = f.replace('.md', '');
+      return { name: `vortexa:${name}`, file: f };
+    });
+
+  let added = 0;
+  for (const skill of skills) {
+    const key = skill.name;
+    const skillPath = path.join(commandsDir, skill.file);
+
+    if (!settings.customCommands[key]) {
+      settings.customCommands[key] = skillPath;
+      added++;
+    }
+  }
+
+  writeSettings(settingsPath, settings);
+  return { total: skills.length, added };
+}
+
+function readManifest(manifestPath) {
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function countFilesByType(files) {
+  const counts = { md: 0, py: 0, json: 0, other: 0 };
+  for (const f of files) {
+    const ext = path.extname(f).slice(1);
+    if (ext in counts) {
+      counts[ext]++;
+    } else {
+      counts.other++;
+    }
+  }
+  return counts;
+}
+
+function setup(targetDir) {
+  const commandsSrc = path.join(packageDir, 'commands', 'vortexa');
+  const contextSrc = path.join(packageDir, 'context');
+  const libSrc = path.join(packageDir, 'lib');
+  const templatesSrc = path.join(packageDir, 'templates');
+  const versionSrc = path.join(packageDir, 'VERSION');
+  const changelogSrc = path.join(packageDir, 'CHANGELOG.md');
+
+  const commandsDest = path.join(targetDir, 'commands', 'vortexa');
+  const vortexaDir = path.join(targetDir, 'vortexa');
+  const contextDest = path.join(vortexaDir, 'context');
+  const libDest = path.join(vortexaDir, 'lib');
+  const templatesDest = path.join(vortexaDir, 'templates');
+
+  ensureDir(targetDir);
+  ensureDir(commandsDest);
+  ensureDir(vortexaDir);
+  ensureDir(contextDest);
+  ensureDir(libDest);
+  ensureDir(templatesDest);
+
+  const allFiles = [];
+
+  const commandFiles = copyDir(commandsSrc, commandsDest, { rewrite: true, targetDir });
+  allFiles.push(...commandFiles);
+
+  const contextFiles = copyDir(contextSrc, contextDest);
+  allFiles.push(...contextFiles);
+
+  const libFiles = copyDir(libSrc, libDest);
+  allFiles.push(...libFiles);
+
+  const templateFiles = copyDir(templatesSrc, templatesDest);
+  allFiles.push(...templateFiles);
+
+  if (fs.existsSync(versionSrc)) {
+    const versionDest = path.join(vortexaDir, 'VERSION');
+    fs.copyFileSync(versionSrc, versionDest);
+    allFiles.push(versionDest);
+  }
+
+  if (fs.existsSync(changelogSrc)) {
+    const changelogDest = path.join(vortexaDir, 'CHANGELOG.md');
+    fs.copyFileSync(changelogSrc, changelogDest);
+    allFiles.push(changelogDest);
+  }
+
+  const manifest = buildManifest(allFiles, version, targetDir);
+  const manifestPath = path.join(targetDir, 'vortexa-manifest.json');
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+
+  const skillReg = mergeSkillRegistrations(targetDir);
+
+  const commandCount = commandFiles.length;
+  const contextCount = contextFiles.length;
+  const libCount = libFiles.length;
+  const templateCount = templateFiles.length;
+
+  console.log(`\nVortexa Claude Skills v${version} installed successfully!\n`);
+  console.log('Files installed:');
+  console.log(`  ~/.claude/commands/vortexa/  (${commandCount} skill files)`);
+  console.log(`  ~/.claude/vortexa/context/   (${contextCount} context docs)`);
+  console.log(`  ~/.claude/vortexa/lib/       (${libCount} Python modules)`);
+  console.log(`  ~/.claude/vortexa/templates/ (${templateCount} template${templateCount !== 1 ? 's' : ''})`);
+  if (skillReg) {
+    console.log(`  ~/.claude/settings.json      (${skillReg.total} skills registered${skillReg.added > 0 ? `, ${skillReg.added} new` : ''})`);
+  }
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. Open Claude Code in any project directory');
+  console.log('  2. Run /vortexa:init to set up your environment');
+  console.log('  3. Run /vortexa:cargo-flows to start querying!');
+  console.log('');
+}
+
+function update(targetDir) {
+  const manifestPath = path.join(targetDir, 'vortexa-manifest.json');
+  const existing = readManifest(manifestPath);
+
+  if (!existing) {
+    console.log('No existing installation found. Running setup instead.\n');
+    setup(targetDir);
+    return;
+  }
+
+  const installedVersion = existing.version;
+
+  if (installedVersion === version) {
+    console.log(`Already up to date (v${version}).`);
+    return;
+  }
+
+  console.log(`Updating from v${installedVersion} to v${version}...\n`);
+
+  setup(targetDir);
+
+  const changelogPath = path.join(packageDir, 'CHANGELOG.md');
+  if (fs.existsSync(changelogPath)) {
+    const changelog = fs.readFileSync(changelogPath, 'utf8');
+    const versionHeader = new RegExp(`^##\\s+.*${version.replace(/\./g, '\\.')}`, 'm');
+    const match = changelog.match(versionHeader);
+
+    if (match) {
+      const start = match.index;
+      const nextHeader = changelog.indexOf('\n## ', start + 1);
+      const section = nextHeader !== -1
+        ? changelog.slice(start, nextHeader).trim()
+        : changelog.slice(start).trim();
+
+      console.log('\nChangelog:');
+      console.log(section);
+      console.log('');
+    }
+  }
+
+  console.log(`Updated from v${installedVersion} to v${version}!`);
+}
+
+function main() {
+  const subcommand = process.argv[2] || 'setup';
+  const targetDir = getTargetDir();
+
+  switch (subcommand) {
+    case 'setup':
+      setup(targetDir);
+      break;
+    case 'update':
+      update(targetDir);
+      break;
+    default:
+      setup(targetDir);
+      break;
+  }
+}
+
+try {
+  main();
+} catch (err) {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+}

package/commands/vortexa/_check-setup.md

@@ -0,0 +1,9 @@
+# Setup Detection
+
+Before executing any Vortexa analytics command, verify both the global install and local environment:
+
+1. Check that `~/.claude/vortexa/VERSION` exists. If not: "Vortexa skills package is not installed. Run: npx @vortexa/claude-skills setup"
+2. Check that `.env` exists in the current project directory. If not: "Vortexa environment not configured in this project. Run /vortexa:init first."
+3. Check that `.env` contains `VORTEXA_API_KEY` and it is not `your_key_here`. If not: "API key not configured. Edit .env and add your Vortexa API key."
+
+If any check fails, stop execution and display the relevant message. Do not attempt to run the query.

package/commands/vortexa/_skill-template.md

@@ -0,0 +1,100 @@
+---
+# SKILL TEMPLATE -- Copy this file and customize for each new /vortexa: data skill
+# Rename to {skill-name}.md (no underscore prefix) to register as /vortexa:{skill-name}
+name: vortexa:{skill-name}
+description: "{One-line description of what this skill does}"
+argument-hint: "{Example natural language query}"
+allowed-tools:
+  - Read
+  - Edit
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+
+<objective>
+{What this skill does in 1-2 sentences. Be specific about which Vortexa endpoint(s) it uses.}
+</objective>
+
+<execution_context>
+## Pre-loaded Context (via CLAUDE.md @imports)
+The following are automatically available -- do NOT re-read them:
+- context/guardrails.md -- NEVER/ALWAYS rules for all Vortexa API calls
+- context/entity-resolution.md -- How to resolve entity names to hex IDs
+- context/date-units.md -- Date parsing rules and unit defaults
+
+## Required Context (Read on demand)
+Read these files before processing the user's query:
+- context/cargo-movements.md (for cargo flow / timeseries queries)
+- context/voyages.md (for vessel voyage queries)
+- context/reference-endpoints.md (for entity lookups when disambiguation needed)
+
+Only read the endpoint doc(s) relevant to this skill.
+</execution_context>
+
+## Setup Check
+@commands/vortexa/_check-setup.md
+
+<process>
+## 1. Parse the Query
+Analyze $ARGUMENTS and identify:
+- **Product**: What commodity? (crude, LNG, clean products, etc.)
+- **Geography**: Origin and/or destination? What layer? (country, port, region)
+- **Activity**: What movement stage? (exports=loading_end, imports=unloading_start, on water, etc.)
+- **Time range**: What period? Apply date-units.md calendar/trailing convention
+- **Unit**: What measurement? Apply date-units.md commodity defaults
+- **Frequency**: Daily/weekly/monthly? Ask if not specified
+- **Vessel filters**: Any class, flag, or size constraints?
+- **Other**: Intra movements, confidence level, STS inclusion, etc.
+
+## 2. Resolve Entity IDs
+For each entity (origin, destination, product, vessel, corporate):
+1. Identify the entity type and layer
+2. Call the correct SDK search method (see entity-resolution.md)
+3. If multiple matches: present disambiguation options to user
+4. If zero matches: suggest alternatives based on fuzzy matching
+
+## 3. Confirm Before Executing (MANDATORY)
+Present the parsed query to the user:
+
+```
+Query: [restate user's natural language question]
+Endpoint: [CargoTimeSeries / CargoMovements / VoyagesSearchEnriched / etc.]
+Activity: [filter_activity value] ([user's term])
+Origin: [name] ([layer])
+Destination: [name] ([layer])
+Product: [name] ([layer])
+Time: [start datetime] -> [end datetime]
+Unit: [unit] ([commodity default or user-specified])
+Frequency: [value or "Please specify: daily/weekly/monthly?"]
+Intra: [exclude_intra_country for exports/imports, all otherwise]
+Additional: [any other filters applied]
+
+Confirm or adjust?
+```
+
+NEVER execute an API call without showing this confirmation.
+Wait for user to confirm or request adjustments.
+
+## 4. Execute Query
+Build and run the Python API call using confirmed parameters.
+Use the lib/ modules for SDK interaction.
+
+## 5. Present Results
+
+### Data Variant (default for query skills)
+1. Display DataFrame with human-readable column names
+2. Provide natural language summary of key findings (top values, trends, notable changes)
+3. Offer: "Export to CSV?"
+
+### Analytics Variant (for analysis skills)
+1. Display Plotly chart
+2. Display supporting DataFrame
+3. Provide natural language summary
+4. Offer: "Export to CSV?"
+
+### Knowledge Variant (for /vortexa:explain)
+1. Provide text explanation only
+2. No data/charts
+</process>