hissuno 0.2.0

package/skills/references/FEEDBACK.md

@@ -0,0 +1,68 @@
+# Feedback Sessions
+
+Customer feedback sessions - conversations from chat widgets, Slack, Intercom, Gong, and other sources.
+
+## Listing
+
+| Filter | CLI Option | Values |
+|--------|-----------|--------|
+| source | `--source <source>` | `widget`, `slack`, `intercom`, `gong`, `api`, `manual` |
+| status | `--status <status>` | `active`, `closing_soon`, `awaiting_idle_response`, `closed` |
+| tags | `--tags <tags>` | Comma-separated tag list |
+| contact_id | `--contact-id <id>` | Contact UUID |
+| search | `--search <query>` | Full-text search within feedback content |
+
+## Detail
+
+`hissuno get feedback <id>` returns:
+
+- Session metadata: name, source, status, tags, message count
+- Full conversation messages (role + content)
+- Page URL and title (for widget sessions)
+- Lifecycle timestamps (first message, last activity, close time)
+- **Relationships** - linked contacts, companies, issues, knowledge sources, product scopes
+
+## Search
+
+Semantic vector search. Falls back to full-text search for sessions that have not been analyzed/embedded yet.
+
+```bash
+hissuno search "checkout flow" --type feedback
+```
+
+## Creation
+
+```bash
+hissuno add feedback
+```
+
+Interactive prompts:
+1. Messages (loop: select role `user`/`assistant` + enter content, empty to finish)
+2. Name/title (optional)
+3. Tags (optional, comma-separated)
+
+**MCP add fields:**
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `messages` | Yes | array | `[{role: "user"|"assistant", content: string}]` |
+| `name` | No | string | Name/title for the session |
+| `tags` | No | string[] | Classification tags |
+
+## Relationships
+
+Feedback sessions connect to:
+- **Contacts** - who sent the feedback
+- **Companies** - via the contact's company
+- **Issues** - bugs or requests surfaced from this conversation
+- **Knowledge sources** - referenced documentation or code
+- **Product scopes** - the product area this feedback relates to
+
+## CLI Examples
+
+```bash
+hissuno list feedback --source intercom --status closed
+hissuno list feedback --contact-id <uuid> --limit 5
+hissuno get feedback <id>
+hissuno add feedback
+```

package/skills/references/GRAPH-TRAVERSAL.md

@@ -0,0 +1,96 @@
+# Knowledge Graph Traversal
+
+Hissuno stores all data in an interconnected knowledge graph. Every entity can link to any other entity via universal edges, enabling rich cross-entity queries.
+
+## Entity Types
+
+| Entity Type | CLI Type | Description |
+|-------------|----------|-------------|
+| `company` | `customers --customer-type companies` | Customer organizations |
+| `contact` | `customers` (default) | Individual people |
+| `issue` | `issues` | Bugs, features, change requests |
+| `session` | `feedback` | Feedback conversations |
+| `knowledge_source` | `knowledge` | Codebases, docs, URLs |
+| `product_scope` | `scopes` | Product areas and initiatives |
+
+## Reading Relationships
+
+Every `hissuno get <type> <id>` call returns a `relationships` section showing all connected entities, grouped by type:
+
+```
+Related Entities:
+  Companies (2): Acme Corp, Globex Inc
+  Contacts (3): Jane Doe, John Smith, Alex Chen
+  Issues (1): Login timeout on mobile
+  Product Scopes (1): API Platform
+```
+
+With `--json`, relationships appear as:
+```json
+{
+  "relationships": {
+    "companies": [{"id": "...", "name": "Acme Corp", "domain": "acme.com"}],
+    "contacts": [{"id": "...", "name": "Jane Doe", "email": "jane@acme.com"}],
+    "issues": [{"id": "...", "title": "Login timeout", "type": "bug", "status": "open"}],
+    "sessions": [],
+    "knowledgeSources": [],
+    "productScopes": [{"id": "...", "name": "API Platform"}]
+  }
+}
+```
+
+## Filtering by Relationship
+
+Some `list` commands accept relationship-based filters:
+
+| Command | Filter | Description |
+|---------|--------|-------------|
+| `hissuno list feedback` | `--contact-id <id>` | Feedback from a specific contact |
+| `hissuno list customers` | `--company-id <id>` | Contacts at a specific company |
+
+The API supports additional relationship filters (`productScopeIds`, `goalId` on issues) not yet exposed in the CLI.
+
+## Common Traversal Patterns
+
+### Issues in a product area
+
+1. `hissuno list scopes` - find the scope ID
+2. `hissuno get scopes <id>` - check relationships.issues
+
+Or via API: `GET /api/issues?productScopeIds=<id>` for filtered listing.
+
+### Feedback from a specific company's contacts
+
+1. `hissuno list customers --company-id <id>` - find contacts at the company
+2. For each contact: `hissuno list feedback --contact-id <id>`
+
+### Issues aligned with a goal
+
+1. `hissuno list scopes` - find the scope, note the goal ID
+2. Via API: `GET /api/issues?goalId=<goalId>` (not yet in CLI)
+3. Alternative: `hissuno get scopes <id>` and check relationships.issues
+
+### Companies affected by an issue
+
+1. `hissuno get issues <id>` - check relationships.companies (shown in related entities)
+
+### Full picture for a contact
+
+1. `hissuno get customers <id>` - returns all relationships in one call:
+   - Company they belong to
+   - Feedback sessions they created
+   - Issues they reported
+   - Product scopes they engage with
+
+### Trace feedback to product impact
+
+1. `hissuno get feedback <id>` - note related issues and product scopes
+2. `hissuno get issues <id>` for each linked issue - see priority, RICE scores
+3. `hissuno get scopes <id>` for the product area - see goals and other related issues
+
+## Tips
+
+- Always use `--json` when building multi-step traversals programmatically
+- `get` is the primary traversal tool - it returns all relationships in one call
+- For large result sets, use `--limit` to control pagination
+- Entity IDs are UUIDs - pass them exactly between commands

package/skills/references/INTEGRATIONS.md

@@ -0,0 +1,83 @@
+# Integrations
+
+Connect external data sources to Hissuno via the CLI or dashboard.
+
+## Supported Platforms
+
+| Platform | Connection | Syncable | Description |
+|----------|-----------|----------|-------------|
+| Intercom | Token or OAuth | Yes | Customer conversations |
+| Gong | Token | Yes | Sales call recordings |
+| Zendesk | Token | Yes | Support tickets |
+| Slack | OAuth | No | Workspace messages |
+| GitHub | OAuth | No | Issues and PRs |
+| Jira | OAuth | No | Issue tracking (auto-sync available) |
+| Linear | OAuth | No | Issue tracking (auto-sync available) |
+
+**Syncable** platforms pull data on a schedule (manual, 1h, 6h, 24h). Non-syncable platforms use real-time hooks or manual import.
+
+## Dashboard-Only Integrations
+
+These integrations are configured through the Hissuno dashboard, not the CLI:
+- Chat widget (embedded on your site)
+- PostHog (product analytics)
+- HubSpot (CRM)
+- Fathom (meeting recordings)
+- Notion (documentation)
+
+## CLI Commands
+
+### List all integrations
+
+```bash
+hissuno integrate                                # Shows status of all 7 platforms
+hissuno integrate --json                         # JSON output
+```
+
+### Interactive setup
+
+```bash
+hissuno integrate <platform>                     # Interactive wizard: shows status, offers connect/configure/sync/disconnect
+```
+
+### Direct actions
+
+```bash
+hissuno integrate <platform> status              # Detailed connection status
+hissuno integrate <platform> connect             # Connect (OAuth opens browser, token prompts for credentials)
+hissuno integrate <platform> configure           # Update sync frequency or settings
+hissuno integrate <platform> sync                # Trigger manual sync (syncable platforms only)
+hissuno integrate <platform> sync --mode full    # Full re-sync (vs incremental)
+hissuno integrate <platform> disconnect          # Disconnect (with confirmation)
+```
+
+### Connection Options
+
+Some platforms accept credentials directly (non-interactive):
+
+**Gong:**
+```bash
+hissuno integrate gong connect --access-key <key> --access-key-secret <secret> --base-url <url> --sync-frequency 24h
+```
+
+**Zendesk:**
+```bash
+hissuno integrate zendesk connect --subdomain <sub> --email <email> --api-token <token> --sync-frequency 24h
+```
+
+**Intercom:**
+```bash
+hissuno integrate intercom connect --access-token <token> --sync-frequency 24h
+```
+
+## Status Details
+
+Each platform returns different status fields when connected:
+
+- **Intercom**: workspace name, auth method, sync frequency, last sync status, conversations synced
+- **Gong**: sync frequency, last sync status, calls synced
+- **Zendesk**: subdomain, account name, sync frequency, last sync status, tickets synced
+- **Slack**: workspace name, domain, installed by
+- **GitHub**: account login, installed by
+- **Jira**: site URL, project key, issue type, auto-sync status
+- **Linear**: organization, team, auto-sync status

package/skills/references/ISSUES.md

@@ -0,0 +1,72 @@
+# Issues
+
+Product issues - bugs, feature requests, and change requests tracked from customer feedback.
+
+## Listing
+
+| Filter | CLI Option | Values |
+|--------|-----------|--------|
+| type | `--issue-type <type>` | `bug`, `feature_request`, `change_request` |
+| priority | `--priority <priority>` | `low`, `medium`, `high` |
+| status | `--status <status>` | `open`, `ready`, `in_progress`, `resolved`, `closed` |
+| search | `--search <query>` | Text search within title and description |
+
+The API also accepts `productScopeIds` (comma-separated UUIDs) and `goalId` filters, but these are not yet exposed as CLI options. Use `--json` with the API directly if you need scope-filtered issue lists.
+
+## Detail
+
+`hissuno get issues <id>` returns:
+
+- Title, description, type, priority, status
+- RICE scores (reach, impact, confidence, effort) when computed
+- Impact analysis and brief (when generated)
+- Upvote count
+- **Relationships** - linked feedback sessions, contacts, companies, knowledge sources, product scopes
+
+## Search
+
+Semantic vector search for finding similar issues by meaning.
+
+```bash
+hissuno search "login failures" --type issues
+```
+
+## Creation
+
+```bash
+hissuno add issues
+```
+
+Interactive prompts:
+1. Type (bug / feature request / change request)
+2. Title
+3. Description
+4. Priority (optional: low / medium / high)
+
+**MCP add fields:**
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `type` | Yes | string | `bug`, `feature_request`, or `change_request` |
+| `title` | Yes | string | Issue title |
+| `description` | Yes | string | Detailed description |
+| `priority` | No | string | `low`, `medium`, or `high` |
+
+## Relationships
+
+Issues connect to:
+- **Feedback sessions** - conversations that surfaced this issue
+- **Contacts** - customers who reported or are affected
+- **Companies** - organizations impacted
+- **Knowledge sources** - relevant code or documentation
+- **Product scopes** - the product area or initiative this issue belongs to (with optional goal alignment)
+
+## CLI Examples
+
+```bash
+hissuno list issues --status open --priority high
+hissuno list issues --issue-type bug
+hissuno get issues <id>
+hissuno search "payment timeout" --type issues
+hissuno add issues
+```

package/skills/references/KNOWLEDGE.md

@@ -0,0 +1,42 @@
+# Knowledge Sources
+
+Analyzed knowledge sources - codebases, documents, and URLs that have been processed into searchable chunks.
+
+## Listing
+
+No filters available. `hissuno list knowledge` returns all knowledge sources.
+
+## Detail
+
+`hissuno get knowledge <id>` returns:
+
+- Name, type (codebase, document, URL), status
+- Processing metadata (chunk count, last analyzed)
+- **Relationships** - linked issues, feedback sessions, product scopes, contacts, companies
+
+## Search
+
+Semantic vector search across all knowledge chunks. Matches by meaning, not exact text.
+
+```bash
+hissuno search "authentication flow" --type knowledge
+```
+
+## Creation
+
+Not supported via CLI or MCP. Add knowledge sources through the Hissuno dashboard.
+
+## Relationships
+
+Knowledge sources connect to all other entity types in the graph. Common connections:
+- **Issues** - bugs or feature requests referencing this codebase/doc
+- **Product scopes** - the product area this knowledge belongs to
+- **Feedback sessions** - customer conversations that reference this knowledge
+
+## CLI Examples
+
+```bash
+hissuno list knowledge                           # List all sources
+hissuno get knowledge <id>                       # Full details + relationships
+hissuno search "payment processing" --type knowledge  # Semantic search
+```

package/skills/references/MCP-TOOLS.md

@@ -0,0 +1,116 @@
+# Hissuno MCP Tools
+
+Alternative to the CLI for agents that support MCP (Claude Desktop, Cursor, etc.). The CLI can do everything the MCP server can, so MCP is only needed if your environment prefers native tool calls over shell commands.
+
+## Setup
+
+The MCP server runs as a Streamable HTTP endpoint alongside the main Hissuno app.
+
+### 1. Start the MCP server
+
+```bash
+# From the Hissuno app directory
+npx tsx src/mcp/app.ts
+```
+
+The server starts on `http://localhost:3100` by default. Override with `MCP_PORT` env var.
+
+### 2. Configure your MCP client
+
+Add to your MCP client config (e.g. `~/.claude/mcp.json` or Cursor settings):
+
+```json
+{
+  "mcpServers": {
+    "hissuno": {
+      "type": "streamable-http",
+      "url": "http://localhost:3100/mcp",
+      "headers": {
+        "Authorization": "Bearer hiss_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### 3. Verify
+
+Health check: `GET http://localhost:3100/health`
+
+## Authentication
+
+- **API key** (required): `Authorization: Bearer hiss_...` - scopes access to the key's project
+- **Contact token** (optional): `X-Contact-Token: <JWT>` - further scopes access to a single contact within the project
+
+## Tools
+
+### `list_resource_types`
+
+Returns all resource types with their filters, search behavior, and add fields. Call this first to understand what data is available.
+
+**Args:** none
+
+### `list_resources`
+
+Browse resources with optional filters.
+
+**Args:**
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `type` | yes | `knowledge`, `feedback`, `issues`, `customers` |
+| `filters` | no | Object of filters (see `list_resource_types` for available filters per type) |
+| `limit` | no | Max results (default: 20, max: 50) |
+
+### `get_resource`
+
+Get full details of a specific resource including relationships.
+
+**Args:**
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `type` | yes | `knowledge`, `feedback`, `issues`, `customers` |
+| `id` | yes | Resource UUID |
+
+### `search_resources`
+
+Semantic search across resources using natural language.
+
+**Args:**
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `query` | yes | Natural language search query |
+| `type` | no | Limit to one type (omit to search all) |
+| `limit` | no | Max results per type (default: 10, max: 20) |
+
+### `add_resource`
+
+Create a new resource. Not available in contact mode.
+
+**Args:**
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `type` | yes | `knowledge`, `feedback`, `issues`, `customers` |
+| `data` | yes | Object with resource fields (see `list_resource_types`) |
+
+### `ask_hissuno`
+
+Ask the Hissuno agent a natural language question. It has access to all knowledge, feedback, issues, and contacts within the project.
+
+**Args:**
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `question` | yes | Your question or request |
+| `thread_id` | no | Thread ID to continue a previous conversation |
+
+## CLI Equivalents
+
+| MCP Tool | CLI Command |
+|----------|-------------|
+| `list_resource_types` | `hissuno types` |
+| `list_resources` | `hissuno list <type>` |
+| `get_resource` | `hissuno get <type> <id>` |
+| `search_resources` | `hissuno search <query>` |
+| `add_resource` | `hissuno add <type>` |
+| `ask_hissuno` | No CLI equivalent |
+
+Note: `scopes` (product scopes) are CLI-only and not available via MCP. `ask_hissuno` is MCP-only.

package/skills/references/PRODUCT-SCOPES.md

@@ -0,0 +1,95 @@
+# Product Scopes
+
+Product areas and initiatives that organize your product into logical groupings. Each scope can have goals - measurable objectives that issues and feedback align against.
+
+CLI type: `scopes` | Entity type in graph: `product_scope`
+
+## Types
+
+| Type | Description |
+|------|-------------|
+| `product_area` | A permanent area of the product (e.g., "Reporting", "API Platform") |
+| `initiative` | A time-bound effort (e.g., "Q1 Mobile Launch", "Auth Migration") |
+
+## Listing
+
+No filters available. `hissuno list scopes` returns all scopes ordered by position.
+
+## Detail
+
+`hissuno get scopes <id>` returns:
+
+- Name, type (product_area or initiative), description
+- Color, position, is_default flag
+- Goals array: `[{id, text}]`
+- **Relationships** - linked issues, feedback sessions, contacts, companies, knowledge sources
+
+## Search
+
+Not available via CLI search. Browse scopes with `list` or look up by ID with `get`.
+
+## Creation
+
+```bash
+hissuno add scopes
+```
+
+Interactive prompts:
+1. Name (required)
+2. Type: product_area or initiative (required)
+3. Description (optional)
+4. Goals (optional, loop: enter goal text, empty to finish, max 10)
+
+**API add fields:**
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `name` | Yes | string | Scope name |
+| `type` | Yes | string | `product_area` or `initiative` |
+| `description` | No | string | Scope description |
+| `goals` | No | array | `[{id, text}]` - measurable objectives |
+
+## Update
+
+```bash
+hissuno update scopes <id>
+```
+
+Interactive prompts to change name, type, description, or manage goals (add, replace, clear).
+
+**API update fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | New name |
+| `type` | string | `product_area` or `initiative` |
+| `description` | string | New description |
+| `goals` | array or null | Replace goals (null to clear) |
+
+## Goals
+
+Goals are measurable objectives attached to a scope. They serve as alignment targets - when the system reviews feedback or analyzes issues, it checks whether they align with active goals.
+
+Example goals for a "Reporting & Analytics" product area:
+- "Enable self-serve data export (CSV, PDF) for non-technical users"
+- "Achieve <2s load time for dashboards with 1M+ rows"
+
+Goal IDs follow the format `g_<timestamp>_<index>` when created via CLI.
+
+## Relationships
+
+Product scopes connect to:
+- **Issues** - bugs and feature requests in this product area (with optional goal alignment metadata)
+- **Feedback sessions** - customer conversations related to this area
+- **Contacts** - customers who engage with this area
+- **Companies** - organizations using this product area
+- **Knowledge sources** - documentation and code for this area
+
+## CLI Examples
+
+```bash
+hissuno list scopes                              # List all scopes
+hissuno get scopes <id>                          # Full details + relationships
+hissuno add scopes                               # Create a new scope
+hissuno update scopes <id>                       # Modify scope or goals
+```