hissuno 0.2.0

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "hissuno",
+  "version": "0.2.0",
+  "description": "Hissuno CLI — set up, connect, and query your product intelligence platform",
+  "type": "module",
+  "bin": {
+    "hissuno": "./bin/hissuno.mjs"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "bin",
+    "skills",
+    "README.md"
+  ],
+  "scripts": {
+    "prebuild": "rm -rf skills && cp -r ../skills/hissuno skills",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "commander": "^13.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "hissuno",
+    "cli",
+    "product-intelligence",
+    "customer-feedback",
+    "api",
+    "rest"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hissuno/hissuno.git",
+    "directory": "app/packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/hissuno/hissuno/issues"
+  },
+  "homepage": "https://github.com/hissuno/hissuno/tree/main/app/packages/cli#readme"
+}

package/skills/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: hissuno
+description: >
+  Use when working with product intelligence data: searching knowledge, browsing feedback,
+  tracking issues, managing customers (contacts and companies), organizing product scopes,
+  traversing the knowledge graph, or connecting data sources via integrations.
+  Works via the hissuno CLI.
+license: MIT
+compatibility: Requires network access to Hissuno API endpoint
+metadata:
+  author: hissuno
+  version: "2.0"
+---
+
+# Hissuno Agent Skill
+
+Hissuno is a unified context layer for product agents. It ingests codebases, docs, and customer signals (from chat widgets, Slack, Intercom, Gong, etc.) into an interconnected knowledge graph - knowledge sources, feedback sessions, product issues, customers (contacts and companies), and product scopes - all linked and traversable.
+
+## Available Data
+
+Hissuno exposes **5 resource types**:
+
+| Type | CLI Type | What It Contains |
+|------|----------|-----------------|
+| **Knowledge** | `knowledge` | Analyzed knowledge sources (codebases, docs, URLs) - searchable via semantic vector search |
+| **Feedback** | `feedback` | Customer feedback sessions - conversations with metadata, tags, and contact links |
+| **Issues** | `issues` | Product issues - bugs, feature requests, and change requests with priority, status, and RICE scores |
+| **Customers** | `customers` | Contacts (people) and companies (organizations) - use `--customer-type` to select |
+| **Product Scopes** | `scopes` | Product areas and initiatives with measurable goals |
+
+See individual reference files in `references/` for detailed filters, fields, and examples per type.
+
+## The Knowledge Graph
+
+All entity types are connected via universal edges. Any entity can link to any other entity. Run `hissuno get <type> <id>` to see all relationships for a resource in a single call. See `references/GRAPH-TRAVERSAL.md` for traversal patterns and multi-step query examples.
+
+## Getting Started
+
+Run `hissuno types` to see all available types, their filters, and creation fields.
+
+## Configuration & Profiles
+
+Connect the CLI and manage multiple environments:
+
+```bash
+hissuno config                      # Interactive setup wizard (API key, URL, project)
+hissuno config show                 # Display active profile, URL, and project
+hissuno profile list                # List all profiles (* marks active)
+hissuno profile use <name>          # Switch active profile
+hissuno profile create <name>       # Create a new profile via config wizard
+hissuno profile delete <name>       # Remove a profile
+```
+
+Install Hissuno skills into agent environments:
+
+```bash
+hissuno skills install              # Install to ~/.claude/skills/hissuno/
+hissuno skills install --cursor     # Install to ~/.cursor/skills/hissuno/
+hissuno skills install --path <dir> # Install to a custom directory
+hissuno skills status               # Check installation status across known locations
+hissuno skills uninstall            # Remove installed skills
+```
+
+## When to Use Which Command
+
+| Goal | Command | Example |
+|------|---------|---------|
+| Understand what data exists | `hissuno types` | "What can I access?" |
+| Browse recent items | `hissuno list <type>` | "Show me open bugs" |
+| Look up a specific item | `hissuno get <type> <id>` | "Get details for issue abc-123" |
+| Find items by meaning | `hissuno search <query>` | "Find feedback about checkout flow" |
+| Create new data | `hissuno add <type>` | "Log a bug about login failures" |
+| Traverse relationships | `hissuno get <type> <id> --json` | "What companies are affected by this issue?" |
+| Connect a data source | `hissuno integrate` | "Connect Intercom" |
+| View current connection | `hissuno config show` | "Which instance am I connected to?" |
+| Switch environment | `hissuno profile use <name>` | "Switch to staging" |
+
+Use `search` for semantic (meaning-based) matching. Use `list` when you want to browse with structured filters (status, priority, source, etc.).
+
+## Common Workflows
+
+### Investigate a Feature Area
+1. `hissuno list scopes` to find the relevant product scope
+2. `hissuno get scopes <id>` to see related issues, feedback, and knowledge
+3. `hissuno get issues <id>` on specific issues for full details and RICE scores
+
+### Find Customer Pain Points
+1. `hissuno list feedback --source intercom --status closed` to see recent conversations
+2. `hissuno search "the problem area"` across all types
+3. Cross-reference with `hissuno list issues --status open` to check existing issues
+
+### Log a Bug from Customer Feedback
+1. `hissuno search "the problem" --type issues` to check for duplicates
+2. If no duplicate: `hissuno add issues` with type=bug, title, description
+3. Optionally reference the feedback session ID in the description
+
+### Analyze a Customer Account
+1. `hissuno list customers --customer-type companies --stage active` to find the company
+2. `hissuno get customers <company-id> --customer-type companies` for company details and contacts
+3. `hissuno list customers --company-id <id>` to find contacts at the company
+4. Cross-reference with `hissuno list feedback --contact-id <id>` for full conversation history
+
+### Assess Goal Progress
+1. `hissuno list scopes` to find the scope
+2. `hissuno get scopes <id>` to see goals and related issues
+3. Review issue statuses and priorities to gauge progress toward each goal
+
+### Switch Between Environments
+1. `hissuno profile list` to see available profiles
+2. `hissuno profile use <name>` to switch
+3. `hissuno config show` to verify the active connection
+
+### Connect a Data Source
+1. `hissuno integrate` to see all integration statuses
+2. `hissuno integrate <platform>` to start the interactive setup wizard
+3. For syncable platforms: `hissuno integrate <platform> sync` to trigger initial data pull
+
+## CLI Reference
+
+The `hissuno` CLI is the primary interface for Claude Code users. See `references/CLI-REFERENCE.md` for the full command reference.
+
+Quick examples:
+```bash
+hissuno types                                    # List resource types
+hissuno list issues --status open --priority high # Browse open high-priority issues
+hissuno list customers                           # List contacts (default)
+hissuno list customers --customer-type companies # List companies
+hissuno list scopes                              # List product areas and initiatives
+hissuno search "checkout flow"                   # Semantic search across all types
+hissuno get feedback <id>                        # Full session detail + relationships
+hissuno get customers <id>                       # Contact details + company relationship
+hissuno add issues                               # Interactive issue creation
+hissuno add scopes                               # Create a product scope with goals
+hissuno update scopes <id>                       # Modify scope name, type, or goals
+hissuno integrate                                # List all integration statuses
+hissuno integrate intercom sync                  # Sync Intercom conversations
+hissuno config show                              # View active connection
+hissuno profile list                             # List profiles
+hissuno profile use staging                      # Switch to staging profile
+hissuno skills install                           # Install skills for Claude Code
+```
+
+## MCP Access (Alternative)
+
+Everything above can also be accessed via MCP tools if you prefer structured tool calls over CLI. See `references/MCP-TOOLS.md` for setup and usage.

package/skills/references/CLI-REFERENCE.md

@@ -0,0 +1,353 @@
+# Hissuno CLI Reference
+
+Complete command reference for the `hissuno` CLI.
+
+## Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output as JSON instead of formatted markdown |
+| `-V, --version` | Show version number |
+| `-h, --help` | Show help |
+
+---
+
+## Commands
+
+### `hissuno setup`
+
+Infrastructure wizard. Sets up a new Hissuno instance from scratch:
+1. Check prerequisites (Node.js 20+, git)
+2. Clone repository
+3. Install dependencies and build widget
+4. Detect/install PostgreSQL with pgvector
+5. Configure `.env.local`
+6. Push database schema
+7. Seed demo data (optional)
+8. Auto-configure CLI (optional)
+9. Start the server
+
+```bash
+npm i -g hissuno
+hissuno setup
+```
+
+---
+
+### `hissuno config`
+
+Manual configuration wizard. Connects the CLI to an existing Hissuno instance:
+1. **Authentication** - enter your API key and Hissuno URL (default: `http://localhost:3000`)
+2. **Project** - auto-detects the project associated with your API key
+3. **Data sources** - optionally connect integrations (Intercom, Gong, Slack, etc.)
+
+```bash
+hissuno config
+```
+
+Saves configuration to `~/.hissuno/config.json`.
+
+---
+
+### `hissuno config show`
+
+Display current configuration (active profile, API key, URL, project).
+
+```bash
+hissuno config show
+hissuno config show --json
+```
+
+Shows the active profile name, masked API key, base URL, and project ID.
+
+---
+
+### `hissuno profile`
+
+Manage multiple CLI profiles for different Hissuno instances or projects.
+
+```bash
+hissuno profile list              # List all profiles (* marks active)
+hissuno profile use <name>        # Switch active profile
+hissuno profile create <name>     # Create a new profile via config wizard
+hissuno profile delete <name>     # Remove a profile
+```
+
+**Subcommands:**
+
+| Subcommand | Args | Description |
+|------------|------|-------------|
+| `list` | | List all profiles with active indicator |
+| `use` | `<name>` (required) | Switch to a different profile |
+| `create` | `<name>` (required) | Run config wizard and save as a named profile |
+| `delete` | `<name>` (required) | Remove a profile (cannot delete the active profile) |
+
+Profiles are stored in `~/.hissuno/config.json` under a `profiles` key.
+
+---
+
+### `hissuno skills`
+
+Install Hissuno skills (SKILL.md + references) into agent environments.
+
+```bash
+hissuno skills install              # Install to ~/.claude/skills/hissuno/
+hissuno skills install --cursor     # Install to ~/.cursor/skills/hissuno/
+hissuno skills install --path <dir> # Install to a custom directory
+hissuno skills install --force      # Overwrite without prompting
+hissuno skills uninstall            # Remove from default location
+hissuno skills uninstall --cursor   # Remove from Cursor location
+hissuno skills status               # Check installation across known locations
+```
+
+**Subcommands:**
+
+| Subcommand | Description |
+|------------|-------------|
+| `install` | Copy bundled skills to an agent environment |
+| `uninstall` | Remove installed skills |
+| `status` | Show install state for Claude Code and Cursor locations |
+
+**Install options:**
+
+| Option | Description |
+|--------|-------------|
+| `--cursor` | Target `~/.cursor/skills/hissuno/` instead of Claude Code |
+| `--path <dir>` | Target a custom directory (mutually exclusive with `--cursor`) |
+| `--force` | Overwrite existing installation without confirmation |
+
+---
+
+### `hissuno status`
+
+Check connection health. Verifies the CLI can reach the configured Hissuno instance.
+
+```bash
+hissuno status
+```
+
+---
+
+### `hissuno types`
+
+List all available resource types with their filters and fields.
+
+```bash
+hissuno types
+hissuno types --json
+```
+
+---
+
+### `hissuno list <type>`
+
+List resources with optional filters.
+
+```bash
+hissuno list feedback
+hissuno list issues --status open --priority high
+hissuno list customers --search "john" --limit 5
+hissuno list customers --customer-type companies --stage active
+hissuno list scopes
+```
+
+**Arguments:**
+| Argument | Description |
+|----------|-------------|
+| `type` | `knowledge`, `feedback`, `issues`, `customers`, `scopes` |
+
+**Options (feedback):**
+| Option | Description |
+|--------|-------------|
+| `--source <source>` | `widget`, `slack`, `intercom`, `gong`, `api`, `manual` |
+| `--status <status>` | `active`, `closing_soon`, `awaiting_idle_response`, `closed` |
+| `--tags <tags>` | Comma-separated tag list |
+| `--contact-id <id>` | Filter by contact UUID |
+| `--search <query>` | Text search |
+
+**Options (issues):**
+| Option | Description |
+|--------|-------------|
+| `--issue-type <type>` | `bug`, `feature_request`, `change_request` |
+| `--priority <priority>` | `low`, `medium`, `high` |
+| `--status <status>` | `open`, `ready`, `in_progress`, `resolved`, `closed` |
+| `--search <query>` | Text search |
+
+**Options (customers):**
+| Option | Description |
+|--------|-------------|
+| `--customer-type <type>` | `contacts` (default) or `companies` |
+| `--search <query>` | Search by name or email (contacts) / name or domain (companies) |
+| `--company-id <id>` | Filter contacts by company UUID |
+| `--role <role>` | Filter contacts by role |
+| `--stage <stage>` | Filter companies by stage (`prospect`, `onboarding`, `active`, `churned`, `expansion`) |
+| `--industry <industry>` | Filter companies by industry |
+
+**Options (scopes):**
+No type-specific filters. Use `--limit` to control result count.
+
+**Common options:**
+| Option | Description |
+|--------|-------------|
+| `--limit <n>` | Max results (default: 20) |
+
+---
+
+### `hissuno get <type> <id>`
+
+Get full details of a specific resource, including all graph relationships.
+
+```bash
+hissuno get issues abc-123
+hissuno get feedback def-456 --json
+hissuno get customers ghi-789
+hissuno get customers xyz-456 --customer-type companies
+hissuno get scopes jkl-012
+```
+
+**Arguments:**
+| Argument | Description |
+|----------|-------------|
+| `type` | `knowledge`, `feedback`, `issues`, `customers`, `scopes` |
+| `id` | Resource UUID |
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--customer-type <type>` | For `customers` type: `contacts` (default) or `companies` |
+
+The `get` command also fetches and displays all related entities (companies, contacts, issues, feedback sessions, knowledge sources, product scopes) for the requested resource.
+
+---
+
+### `hissuno search <query>`
+
+Search across resources using natural language (semantic search).
+
+```bash
+hissuno search "checkout flow issues"
+hissuno search "login failures" --type issues
+hissuno search "payment" --type customers --limit 5 --json
+```
+
+**Arguments:**
+| Argument | Description |
+|----------|-------------|
+| `query` | Natural language search query |
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--type <type>` | Limit to one type: `knowledge`, `feedback`, `issues`, `customers` |
+| `--limit <n>` | Max results (default: 10) |
+
+Note: `scopes` is not searchable via this command. `customers` search covers contacts only (companies don't have semantic search).
+
+---
+
+### `hissuno add <type>`
+
+Create a new resource interactively. Prompts for required fields.
+
+```bash
+hissuno add issues      # Create a bug, feature request, or change request
+hissuno add customers   # Create a contact or company (prompts for sub-type)
+hissuno add customers --customer-type companies  # Create a company directly
+hissuno add feedback    # Log a feedback session
+hissuno add scopes      # Create a product scope with optional goals
+```
+
+**Supported types:** `issues`, `customers`, `feedback`, `scopes`
+
+Knowledge sources cannot be added via CLI (use the Hissuno dashboard).
+
+**Interactive prompts by type:**
+
+**issues:**
+- Type (bug / feature request / change request)
+- Title
+- Description
+- Priority (optional: low / medium / high)
+
+**customers (contacts):**
+- Name
+- Email
+- Role (optional)
+- Title (optional)
+- Phone (optional)
+- Company ID (optional)
+- Is champion? (optional)
+
+**customers (companies):**
+- Company name
+- Domain (e.g., acme.com)
+- Industry (optional)
+- ARR (optional, number)
+- Stage (optional: prospect / onboarding / active / churned / expansion)
+- Employee count (optional, number)
+- Plan tier (optional)
+- Country (optional)
+- Notes (optional)
+
+**feedback:**
+- Messages (loop: select role + enter content, empty to finish)
+- Name/title (optional)
+- Tags (optional, comma-separated)
+
+**scopes:**
+- Name
+- Type (product_area / initiative)
+- Description (optional)
+- Goals (optional, loop: enter goal text, empty to finish, max 10)
+
+---
+
+### `hissuno update <type> <id>`
+
+Update an existing resource interactively.
+
+```bash
+hissuno update scopes <id>
+```
+
+**Supported types:** `scopes`
+
+**Interactive prompts (scopes):**
+- Change name? (shows current)
+- Change type? (shows current)
+- Change description?
+- Manage goals? (add new, replace all, clear all, or keep current)
+
+---
+
+### `hissuno integrate [platform] [action]`
+
+Manage integrations with external platforms.
+
+**Supported platforms:** `intercom`, `gong`, `zendesk`, `slack`, `github`, `jira`, `linear`
+
+```bash
+hissuno integrate                                # List all integrations with status
+hissuno integrate <platform>                     # Interactive setup wizard
+hissuno integrate <platform> status              # Detailed status
+hissuno integrate <platform> connect             # Connect (OAuth or token)
+hissuno integrate <platform> configure           # Update settings
+hissuno integrate <platform> sync                # Trigger manual sync
+hissuno integrate <platform> disconnect          # Disconnect
+```
+
+**Platform-specific connect options:**
+
+| Option | Platforms | Description |
+|--------|-----------|-------------|
+| `--access-key <key>` | gong | Access key |
+| `--access-key-secret <secret>` | gong | Access key secret |
+| `--base-url <url>` | gong | Base URL (default: https://api.gong.io) |
+| `--subdomain <sub>` | zendesk | Zendesk subdomain |
+| `--email <email>` | zendesk | Admin email |
+| `--api-token <token>` | zendesk | API token |
+| `--access-token <token>` | intercom | Access token |
+| `--sync-frequency <freq>` | gong, zendesk, intercom | `manual`, `1h`, `6h`, `24h` |
+| `--mode <mode>` | sync action | `incremental` (default) or `full` |
+
+See `references/INTEGRATIONS.md` for full platform details.

package/skills/references/COMPANIES.md

@@ -0,0 +1,51 @@
+# Companies
+
+Customer companies with revenue data, health scores, and contact associations. Part of the "customers" umbrella alongside contacts.
+
+## CLI Support
+
+Companies are accessible via the `customers` type with `--customer-type companies`.
+
+```bash
+hissuno list customers --customer-type companies                      # List all companies
+hissuno list customers --customer-type companies --stage active       # Filter by stage
+hissuno list customers --customer-type companies --industry SaaS      # Filter by industry
+hissuno get customers <id> --customer-type companies                  # Company details
+hissuno add customers --customer-type companies                       # Create a company
+```
+
+## Key Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| name | string | Company name |
+| domain | string | Company domain (e.g., acme.com) |
+| industry | string | Industry sector |
+| arr | number | Annual recurring revenue |
+| stage | string | Customer stage (prospect, active, churned, etc.) |
+| health_score | integer | 0-100 health score |
+| renewal_date | timestamp | Next renewal date |
+| plan_tier | string | Subscription tier |
+
+## Relationships
+
+Companies connect to:
+- **Contacts** - people at this company
+- **Feedback sessions** - conversations from company contacts
+- **Issues** - bugs or requests affecting this company
+- **Knowledge sources** - relevant documentation
+- **Product scopes** - product areas this company uses
+
+## CLI Examples
+
+```bash
+hissuno list customers --customer-type companies                      # List all companies
+hissuno list customers --customer-type companies --stage active       # Active companies
+hissuno list customers --customer-type companies --search "acme"      # Search by name/domain
+hissuno get customers <id> --customer-type companies                  # Full company details
+hissuno add customers --customer-type companies                       # Create interactively
+```
+
+Also accessible through relationships:
+- Contact relationships: `hissuno get customers <contact-id>` shows the linked company
+- Issue/feedback relationships: `hissuno get issues <id>` shows related companies in the graph

package/skills/references/CONTACTS.md

@@ -0,0 +1,83 @@
+# Contacts
+
+Individual customer contacts with linked feedback history and company associations. Part of the "customers" umbrella alongside companies.
+
+## Listing
+
+```bash
+hissuno list customers                              # List contacts (default)
+hissuno list customers --customer-type contacts      # Explicit contacts
+hissuno list customers --search "john" --limit 5
+hissuno list customers --company-id <uuid>
+```
+
+| Filter | CLI Option | Values |
+|--------|-----------|--------|
+| search | `--search <query>` | Search by name or email |
+| company_id | `--company-id <id>` | Filter by company UUID |
+| role | `--role <role>` | Filter by role |
+
+## Detail
+
+`hissuno get customers <id>` returns:
+
+- Name, email, phone, title, role
+- Company association (company ID and URL)
+- Champion status
+- Last contacted timestamp
+- Notes, custom fields
+- **Relationships** - linked feedback sessions, issues, companies, knowledge sources, product scopes
+
+## Search
+
+Semantic vector search. Falls back to name/email text matching for contacts without embeddings.
+
+```bash
+hissuno search "john" --type customers
+```
+
+## Creation
+
+```bash
+hissuno add customers                          # Prompts for sub-type
+hissuno add customers --customer-type contacts # Direct to contact creation
+```
+
+Interactive prompts:
+1. Name (required)
+2. Email (required)
+3. Role (optional)
+4. Title (optional)
+5. Phone (optional)
+6. Company ID (optional)
+7. Is champion? (optional)
+
+**MCP add fields:**
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `name` | Yes | string | Full name |
+| `email` | Yes | string | Email address |
+| `role` | No | string | Role/position |
+| `title` | No | string | Job title |
+| `phone` | No | string | Phone number |
+| `company_id` | No | string | UUID of associated company |
+| `is_champion` | No | boolean | Whether this is a product champion |
+
+## Relationships
+
+Contacts connect to:
+- **Companies** - the organization they belong to
+- **Feedback sessions** - conversations from this contact
+- **Issues** - bugs or requests they reported
+- **Knowledge sources** - documentation they referenced
+- **Product scopes** - product areas they engage with
+
+## CLI Examples
+
+```bash
+hissuno list customers --search "john" --limit 5
+hissuno list customers --company-id <uuid>
+hissuno get customers <id>
+hissuno add customers --customer-type contacts
+```