@ameshkin/ticket-mate 0.1.20

package/README.md

@@ -0,0 +1,1214 @@
+# TICKET MATE
+
+### QUICK NOTES
+
+1. Test tickets with `ticket-mate sync --ticket NOVA-123`
+
+## CURSOR DO NOT UPDATE THIS FILE
+
+**Jira integration and AI execution layer** - Bridges Jira tickets and AI-assisted development workflows.
+
+### Jira AppSettings
+
+https://developer.atlassian.com/console/myapps/
+
+## Overview
+
+`@ameshkin/ticket-mate` is a production-ready npm package that provides comprehensive Jira integration capabilities. It includes a CLI interface, REST API server, Next.js dashboard, and automation features for managing Jira tickets, syncing progress files, generating AI prompts, building PR descriptions, and automating ticket creation from JSON files.
+
+## Database
+
+https://console.prisma.io/cmixzg6nk03vo2sflg2pzq64u/cmixzgvue03sd1efplmdnimkj/cmixzgvue03se1efpm49q18z0/studio#table=users&schema=public&view=table
+
+## Error Logs
+
+```bash
+
+
+vercel logs ticket-mate.app
+
+```
+
+## Vercel Environment Variables
+
+```bash
+# list env
+vercel env ls
+
+
+# pull all production vars into a test file .test-prod.env
+vercel env pull .test-prod.env --environment=production
+
+
+# Or if you want all environments in one file:
+vercel env pull .env.vercel.production --environment=production
+
+            "code": "OLLAMA_MODEL_MISSING",
+            "message": "Model \"qwen2.5-coder:latest\n\" is not installed on http://72.61.71.227:11434. Using fallback \"qwen2.5-coder:latest\".",
+            "requested": "qwen2.5-coder:latest\n",
+            "fallbackUsed": "qwen2.5-coder:latest"
+
+
+vercel env add GITHUB_CLIENT_ID development
+# paste the value when prompted
+
+vercel env add GITHUB_CLIENT_SECRET development
+
+vercel env add NEXTAUTH_URL development
+
+
+#remove if exists undefined
+#https://jira-mate.vercel.app
+vercel env ls production
+vercel env rm NEXTAUTH_URL production --yes
+
+
+vercel env add OLLAMA_DEMO_MODEL production
+vercel env add OLLAMA_DEMO_MODEL development
+vercel env add OLLAMA_DEMO_MODEL preview
+
+vercel env add OLLAMA_CODE_MODEL development
+
+OLLAMA_CODE_MODEL
+
+qwen2.5-coder:7b
+
+vercel env add NEXTAUTH_URL production
+=https://ticket-mate.app
+
+
+#https://ticket-mate.app
+
+OLLAMA_CODE_MODEL=
+OLLAMA_DEMO_MODEL=
+
+# AI Runtime Configuration
+AI_RUNTIME=auto
+
+
+# VERCEL LOGS
+
+
+vercel logs ticket-mate.app
+
+RESEND_API_KEY=re_36qa2oNt_HyHhz8N9AXjtmnCkcDUGa3Wh
+
+
+
+vercel env add DATABASE_URL production
+#postgres://3bc59484969a8f4dd008a6300b7c79daa72fc00ec9db1d3545013fe8e48afd0c:sk_IJnKo655RyEjZhfoDiGel@db.prisma.io:5432/postgres?sslmode=require
+#
+#
+#ATLASSIAN_WEBHOOK_PATH="/api/webhooks/jira"
+#ATLASSIAN_PROJECT_KEY=JM
+
+
+hostinger ollama
+root
+
+Brootgroot17+
+
+export OLLAMA_BASE_URL="http://72.61.71.227:8080"
+export OLLAMA_DEMO_MODEL="qwen2.5-coder:latest"
+
+
+
+vercel env add GITHUB_CLIENT_ID development
+
+
+
+cp /Users/amirmeshkin/_code/_work/proveoautomation/CHAT/Web/frontend/src/pages/admin/profile/ProfilePage.tsx
+
+
+
+
+OLLAMA_BASE_URL
+
+```
+
+### Ollama Server
+
+```bash
+ssh root@72.61.71.227
+
+
+ssh -i /Users/amirmeshkin/.ssh/hostinger_ollama root@72.61.71.227
+
+
+
+ollama pull qwen2.5-coder:14b
+
+ollama run qwen2.5-coder:14b
+
+
+ollama pull deepseek-coder
+
+
+
+
+```
+
+### ORC MCP
+
+LOCAL
+
+```
+ORC_MCP_BASE_URL=http://localhost:7777
+
+
+ORC_MCP_BASE_URL=http://localhost:7777
+ORC_MCP_CLIENT_ID=ticket-mate-internal
+ORC_MCP_CLIENT_SECRET=sfagsdgfhmfghjrty
+ORC_MCP_TIMEOUT_MS=30000
+ORC_MCP_DRY_RUN_DEFAULT=true
+```
+
+cp -R \
+"/Users/amirmeshkin/\_code/my-npm-packages/orchestrator-core" \
+"/Users/amirmeshkin/\_code/my-npm-packages/orchestrator/\_packages/nevaroAI/"
+
+```bash
+
+# copy CHAT from component examples to CHAT
+
+
+cp -R \
+"/Users/amirmeshkin/_code/_work/proveoautomation/component-examples/CHAT/" \
+"/Users/amirmeshkin/_code/_work/proveoautomation/CHAT"
+
+
+
+
+
+# copy CHAT from CHAT back to COMPONENT
+
+
+cp -R \
+"/Users/amirmeshkin/_code/_work/proveoautomation/CHAT/" \
+"/Users/amirmeshkin/_code/_work/proveoautomation/component-examples/CHAT"
+
+```
+
+### Demo Account and Page
+
+https://www.ticket-mate.app/demo
+
+demo@gmail.com
+welcome123
+
+## Ticket Mate v1.0 Roadmap
+
+Ticket Mate v1.0 unifies four pillars into a single coherent flow:
+
+- ✅ **Ticket Mate CLI + `.ticket-mate`** - Command-line tools that sync Jira tickets to local markdown files
+- ✅ **Next.js Admin UI + Webhook** - Web interface for viewing and managing tickets, bugs, and AI-assisted planning
+- ⏳ **Replit Extension** - In-editor tool tab for working with tickets and bugs directly in Replit
+- ✅ **Orchestrator-derived `bugs.json`** - Unified bug tracking that can be promoted to Jira Bug issues
+
+All four pillars share the same data structures and read from the same `.ticket-mate` directory, ensuring consistency across tools.
+
+**Progress:** 75% Complete (3 of 4 pillars fully implemented)
+
+**Completed Features:**
+
+- ✅ CLI with 20+ commands (`tm`, `ticket-mate`)
+- ✅ `.ticket-mate` file-based integration
+- ✅ Next.js Admin UI with full dashboard
+- ✅ OAuth authentication (GitHub, Google, Atlassian, Apple, Credentials)
+- ✅ Jira REST API client
+- ✅ Ticket syncing to markdown files
+- ✅ AI prompt generation
+- ✅ Board management with AI columns
+- ✅ Bugs.json integration
+- ✅ Webhook handling
+- ✅ Git integration (branch/commit validation)
+
+**In Progress:**
+
+- ⏳ Replit Extension (planned - architecture defined, implementation pending)
+
+**Recent Completions (2025-01-12):**
+
+- ✅ Local email/password authentication
+- ✅ OAuth security enhancements (CSRF protection, token encryption)
+- ✅ Authentication-aware data fetching
+- ✅ Production deployment (ticket-mate.app)
+- ✅ Branding update (Ticket Mate → Ticket Mate)
+- ✅ Ticket organization restructured (`.orchestrator/tickets/`)
+
+**Tracking:**
+
+- Progress: [`.orchestrator/tickets/`](.orchestrator/tickets/)
+  - Epics: [`.orchestrator/tickets/epics/`](.orchestrator/tickets/epics/) (2 files)
+  - Stories: [`.orchestrator/tickets/stories/`](.orchestrator/tickets/stories/) (1 file)
+  - Bugs: [`.orchestrator/tickets/bugs/`](.orchestrator/tickets/bugs/) (5 files)
+  - Tasks: [`.orchestrator/tickets/tasks/`](.orchestrator/tickets/tasks/) (9 files)
+- Master Progress: [`.orchestrator/master-progress.md`](.orchestrator/master-progress.md)
+
+**Documentation:**
+
+- **[User Guide](docs/user-guide.md)** - Comprehensive guide for features and usage.
+- **[API Documentation](docs/api.md)** - Reference for API endpoints.
+
+## Features
+
+### Core Features
+
+- ✅ **[Jira Integration](docs-dev/JIRA-AUTH-ISSUE.md)** - Full REST API client for Jira operations (OAuth + PAT support)
+- ✅ **[Ticket Syncing](docs-dev/COMMANDS.md)** - Sync Jira tickets to markdown files for documentation
+- ✅ **[AI Prompts](docs-dev/AI-WORKFLOW.md)** - Generate AI-consumable prompts from ticket briefs
+- ✅ **[PR Builder](docs-dev/COMMANDS.md)** - Generate structured PR descriptions from tickets
+- ✅ **[CLI Interface](docs-dev/COMMANDS.md)** - 20+ command-line tools (`tm`, `ticket-mate`)
+- ✅ **[REST API Server](docs-dev/API-REPORT.md)** - Next.js API routes with authentication
+- ✅ **[Next.js Dashboard](docs-dev/NEW-PAGES-REFERENCE.md)** - Full web UI for projects, boards, tickets, and admin
+- ✅ **Board Management** - Create boards, add columns (including "AI: In Progress")
+- ✅ **[Automation](docs-dev/AUTOMATION-GUIDE.md)** - Process JSON files (bugs-wip.json) and create Jira tickets
+- ✅ **Git Integration** - Branch and commit message validation
+- ✅ **[Webhook Handling](docs-dev/WEBHOOK-TESTING.md)** - Process Jira webhook events with security validation
+- ✅ **Acceptance Criteria** - Extract and sync from test files
+- ✅ **[File-based Integration](docs-dev/AGENT-HANDLER-INTEGRATION.md)** - Repository-based ticket management for AI agents
+- ✅ **[Authentication](docs-dev/AUTH-MODES.md)** - Local email/password + OAuth (GitHub, Google, Atlassian, Apple)
+- ✅ **Token Management** - AI token usage tracking and limits
+
+### Phase 5 Features (Completed)
+
+- ✅ **Authority** - End-to-end provenance for audits.
+- ✅ **Reliability** - Quality gates and health scorecards.
+- ✅ **Contracts** - Team agreement management.
+- ✅ **Automation** - Workflow builder (Triggers/Actions).
+- ✅ **Events** - Real-time observability feed.
+- ✅ **Usage** - Credit consumption tracking.
+
+### Advanced Features
+
+- ✅ **[AI Execution Integration](docs-dev/AI-WORKFLOW.md)** - Execute tickets with AI agents
+- ✅ **Queue Processing** - Process queues of AI-ready tickets
+- ✅ **Batch Operations** - Bulk sync and status updates
+- ✅ **Observability** - Metrics and logging
+- ✅ **Template System** - Customizable markdown templates
+- ✅ **[Multi-tenant Support](docs-dev/ACCOUNT-USER-MODEL.md)** - Account-based organization with seat management
+- ✅ **Subscription Management** - Plan tiers, billing, and usage limits
+
+## Feature Spotlight
+
+### 🤖 AI-Driven Workflow
+
+Ticket Mate bridges the gap between Jira and AI agents. It converts tickets into context-rich prompts that agents can understand.
+
+```typescript
+import { buildTicketPrompts } from "@ameshkin/ticket-mate";
+
+// Generate a comprehensive prompt for an AI agent
+const prompts = await buildTicketPrompts({
+  ticketKey: "NOVA-123",
+  // Includes ticket details, acceptance criteria, and plan
+  markdownPath: ".orchestrator/tickets/tasks/NOVA-123.md",
+  repoRoot: process.cwd(),
+});
+
+console.log(prompts.system); // "You are an expert engineer..."
+console.log(prompts.task); // "Implement feature X following these criteria..."
+```
+
+### ⚡ Automated Bug Filing
+
+Turn JSON reports or linter output into Jira tickets automatically, preventing issue drift.
+
+```bash
+# Process a bugs.json file and create/update Jira tickets
+ticket-mate process-bugs --file ./reports/security-audit.json --sync-status
+```
+
+```typescript
+// Programmatic automation
+import { processJsonInstructionsDirect } from "@ameshkin/ticket-mate/api/automation";
+
+await processJsonInstructionsDirect(
+  {
+    bugs: [{ title: "Memory Leak in Auth", severity: "critical" }],
+  },
+  { projectKey: "PROJ" }
+);
+```
+
+### 🔐 Secure Multi-Mode Auth
+
+Switch seamlessly between Personal Access Tokens for CLI usage and OAuth for SaaS deployment.
+
+```env
+# Mode 1: Personal Access Token (CLI / Local)
+ATLASSIAN_AUTH_MODE=PAT
+ATLASSIAN_EMAIL=me@example.com
+ATLASSIAN_API_KEY=my-token
+
+# Mode 2: OAuth 2.0 (SaaS / Multi-user)
+ATLASSIAN_AUTH_MODE=OAUTH
+ATLASSIAN_CLIENT_ID=...
+ATLASSIAN_CLIENT_SECRET=...
+```
+
+For a deep dive into all features and architecture, see the **[Developer Documentation Index](docs-dev/README.md)**.
+
+## Installation
+
+### From GitHub Packages (Private)
+
+First, configure npm to use GitHub Packages for the `@ameshkin` scope:
+
+```bash
+# Create or edit .npmrc in your project root
+echo "@ameshkin:registry=https://npm.pkg.github.com" >> .npmrc
+echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN" >> .npmrc
+```
+
+Then install:
+
+```bash
+npm install @ameshkin/ticket-mate
+```
+
+**Note**: You need a GitHub Personal Access Token (PAT) with `read:packages` permission to install private packages.
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file or set environment variables:
+
+#### Required Jira Configuration
+
+```env
+ATLASSIAN_BASE_URL=https://pamcms.atlassian.net
+ATLASSIAN_EMAIL=your-email@example.com
+ATLASSIAN_API_KEY=your-api-token
+```
+
+**Optional:**
+
+```env
+ATLASSIAN_PROJECT_KEY=YOUR_PROJECT  # Optional: CLI prefers --project flag or config file
+```
+
+- Generate your Jira API token at: https://id.atlassian.com/manage-profile/security/api-tokens
+- **Important**: Your Jira user must have "Create Issues" permission in the project
+- **[Setup Jira Keys Guide](docs/SETUP-JIRA-KEYS.md)** - Complete guide for getting and configuring all Jira keys
+- See [Permissions & Access Guide](docs/PERMISSIONS-AND-ACCESS.md) for complete setup
+- See [Quick Permission Fix](docs/QUICK-PERMISSION-FIX.md) if you get permission errors
+- See [Jira Setup Guide](docs/jira/JIRA-SETUP.md) for detailed instructions
+- See [ATLASSIAN_SCOPES.md](ATLASSIAN_SCOPES.md) for required OAuth scopes
+
+#### Authentication Modes
+
+ticket-mate supports two authentication modes:
+
+1. **Personal Access Token (PAT)** - Default mode
+
+   - Uses `ATLASSIAN_EMAIL` + `ATLASSIAN_API_KEY` for Basic Auth
+   - Simple setup, good for local dev and single-user scenarios
+   - Optional: `ATLASSIAN_CLOUD_ID` for Cloud API calls (not required)
+   - Set `ATLASSIAN_AUTH_MODE=PAT` explicitly, or leave unset (defaults to PAT)
+
+2. **OAuth 2.0** - For production/SaaS
+   - Uses `ATLASSIAN_CLIENT_ID` + `ATLASSIAN_CLIENT_SECRET` in env
+   - Per-user tokens and `cloudId` stored in database (not in env)
+   - Multi-user support, per-user authentication
+   - Set `ATLASSIAN_AUTH_MODE=OAUTH` to enable
+   - **Atlassian Developer Console**: [View/Manage OAuth Apps](https://developer.atlassian.com/console/myapps/)
+   - **Required Callback URLs** (register both in Atlassian Developer Console, one per line):
+     - `http://localhost:4000/api/auth/callback/atlassian` (local dev)
+     - `https://ticket-mate.app/api/auth/callback/atlassian` (production)
+   - **Environment Variables**:
+     - Local: `NEXTAUTH_URL="http://localhost:4000"`, `ATLASSIAN_CLIENT_ID`, `ATLASSIAN_CLIENT_SECRET`
+     - Production: `NEXTAUTH_URL="https://ticket-mate.app"`, `ATLASSIAN_CLIENT_ID`, `ATLASSIAN_CLIENT_SECRET`
+   - See [OAuth Setup Guide](docs/OAUTH-SETUP.md) for details
+   - See [OAuth Callback URL Setup](docs/OAUTH-CALLBACK-URL-SETUP.md) for callback URL configuration
+
+**Important Notes:**
+
+- `ATLASSIAN_CLOUD_ID` is **not required** in env. In PAT mode it's optional for Cloud API. In OAuth mode it's stored per-connection in the database.
+- `ATLASSIAN_PROJECT_KEY` is **optional**. CLI prefers `--project` flag or config file. Use env only as fallback.
+- If you previously used `ATLASSIAN_API_TOKEN`, rename it to `ATLASSIAN_API_KEY`. The old variable is deprecated.
+
+#### Cloud API Configuration (for Scoped API Tokens)
+
+If you're using Atlassian scoped API tokens and projects/keys don't appear, enable cloud API mode:
+
+```env
+ATLASSIAN_USE_CLOUD_API=true
+ATLASSIAN_CLOUD_ID=your-cloud-id
+```
+
+**How to find your Cloud ID:**
+
+1. Go to https://admin.atlassian.com
+2. Select your site
+3. Copy the Cloud ID from the URL or site settings
+
+**When to use Cloud API:**
+
+- Using scoped API tokens (long tokens starting with `ATATT3x...`)
+- Projects are not appearing with standard configuration
+- Getting 403/404 errors when listing projects
+
+**Cloud API URL format:**
+
+- Standard: `https://pamcms.atlassian.net/rest/api/3`
+- Cloud API: `https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3`
+
+Alternatively, add to your `jira.json`:
+
+```json
+{
+  "baseUrl": "https://pamcms.atlassian.net",
+  "email": "your-email@example.com",
+  "apiToken": "your-token",
+  "cloudId": "your-cloud-id",
+  "useCloudApi": true
+}
+```
+
+#### API Authentication (for Next.js API routes)
+
+```env
+TICKET_MATE_API_KEY=your-secure-api-key
+NEXT_PUBLIC_TICKET_MATE_API_KEY=your-secure-api-key
+```
+
+#### Dashboard Configuration (for Next.js dashboard)
+
+```env
+NEXT_PUBLIC_ATLASSIAN_BASE_URL=https://pamcms.atlassian.net
+```
+
+**Important**: Never commit `.env` files - they contain sensitive credentials.
+
+## Quick Start
+
+### CLI Usage
+
+```bash
+# Test configuration
+ticket-mate config:test
+
+# Sync a single ticket
+ticket-mate sync --ticket NOVA-123
+
+# Sync all tickets in project
+ticket-mate sync --all
+
+# Generate AI prompt from ticket
+ticket-mate prompt NOVA-123
+
+# List projects
+ticket-mate ls-projects
+
+# List issues
+ticket-mate ls-issues --status "In Progress"
+
+# Create a board with AI column
+ticket-mate create-board --name "Cursor Board" --ai-column
+
+# Process bugs from JSON file
+ticket-mate process-bugs --file public/bugs.json
+
+# Show project information
+ticket-mate project-info
+ticket-mate project-info --health  # Include health check
+
+# Run health check
+ticket-mate health-check
+ticket-mate health-check --fix  # Attempt to fix issues
+
+# Quick sync with progress indicators
+ticket-mate quick-sync --ticket NOVA-123
+ticket-mate quick-sync --all
+
+# Export tickets to various formats
+ticket-mate export --format json --output tickets.json
+ticket-mate export --format csv --status "In Progress"
+ticket-mate export --format markdown --label "AI-READY"
+
+# Batch operations
+ticket-mate batch --keys "NOVA-123,NOVA-124" --action transition --status "Done"
+ticket-mate batch --file tickets.txt --action comment --comment "Reviewed"
+ticket-mate batch --keys "NOVA-123" --action update --labels "reviewed,tested"
+
+# Export and batch operations
+ticket-mate export --format json --output tickets.json
+ticket-mate batch --keys "NOVA-123,NOVA-124" --action transition --status "Done"
+```
+
+### Programmatic Usage
+
+```typescript
+import {
+  getJiraConfig,
+  syncSingleTicket,
+  buildTicketPrompts,
+  listProjects,
+} from "@ameshkin/ticket-mate";
+
+// Get configuration
+const config = getJiraConfig();
+
+// Sync a ticket
+const result = await syncSingleTicket("NOVA-123", config);
+
+// Generate AI prompts
+const prompts = await buildTicketPrompts({
+  ticketKey: "NOVA-123",
+  markdownPath: ".orchestrator/tickets/epics/NOVA-10/NOVA-123.md",
+  repoRoot: process.cwd(),
+});
+
+// List projects
+const projects = await listProjects();
+```
+
+### Next.js Dashboard
+
+The package includes a Next.js dashboard. Start it with:
+
+```bash
+npm run dev
+```
+
+Then visit `http://localhost:4000` to see the dashboard with projects and boards.
+
+## Usage
+
+### CLI Commands
+
+#### Sync Commands
+
+```bash
+# Sync specific ticket
+ticket-mate sync --ticket NOVA-123
+
+# Sync epic and all tickets
+ticket-mate sync --epic NOVA-10
+
+# Sync all tickets
+ticket-mate sync --all
+
+# Custom output directory
+ticket-mate sync --all --output .custom-progress
+```
+
+#### Issue Management
+
+```bash
+# List projects
+ticket-mate ls-projects
+
+# List issues with filters
+ticket-mate ls-issues --project NOVA --status "In Progress"
+ticket-mate ls-issues --assignee me --label AI-READY
+ticket-mate ls-issues --jql "project = NOVA AND status = 'In Progress'"
+
+# Show issue details
+ticket-mate show-issue NOVA-123
+```
+
+#### Board Management
+
+```bash
+# Create board with AI column
+ticket-mate create-board --name "Cursor Board" --ai-column
+
+# List boards for project
+ticket-mate create-board --list
+
+# Create board without AI column
+ticket-mate create-board --name "Team Board" --no-ai-column
+```
+
+#### Automation
+
+```bash
+# Process bugs from JSON file
+ticket-mate process-bugs --file public/bugs.json
+
+# Watch for changes and auto-process
+ticket-mate watch-bugs --file public/bugs.json --auto-process
+
+# Sync bug statuses from Jira
+ticket-mate process-bugs --file public/bugs.json --sync-status
+```
+
+#### AI & Prompts
+
+```bash
+# Generate AI prompt from a ticket
+ticket-mate prompt NOVA-123
+
+# Save prompt to file
+ticket-mate prompt NOVA-123 --output nova-123.md
+
+# Execute AI-assisted work
+ticket-mate execute NOVA-123
+
+# Process queue of AI-ready tickets
+ticket-mate queue
+```
+
+#### Git Validation
+
+```bash
+# Validate branch name
+ticket-mate validate-branch feature/NOVA-123-checkout
+
+# Validate commit message
+ticket-mate validate-commit "NOVA-123: Add checkout functionality"
+```
+
+#### Other Commands
+
+```bash
+# Check sync status
+ticket-mate status
+
+# Test configuration
+ticket-mate config:test
+
+# Create task folder
+ticket-mate create-task-folder NOVA-123
+
+# Sync acceptance criteria
+ticket-mate sync-acceptance NOVA-123
+
+# Interactive menu
+ticket-mate interactive
+```
+
+### File-based Integration: `.ticket-mate`
+
+Ticket Mate provides a file-based integration system that allows AI agents (Cursor, Replit, etc.) to work with Jira tickets directly in your repository. This integration uses a `.ticket-mate` directory structure that is committed to Git and can be used by any AI agent.
+
+### Quick Start
+
+```bash
+# Initialize repository for Ticket Mate integration
+tm init-repo --jira-base-url https://pamcms.atlassian.net --jira-project-key YOUR_PROJECT
+
+# Sync tickets from Jira
+tm sync-tickets
+
+# Show status of local tickets
+tm status
+
+# Emit instructions for AI agents
+tm emit-agent-instructions --agent cursor
+```
+
+### Directory Structure
+
+The `.ticket-mate` directory structure:
+
+```
+.ticket-mate/
+  config.json              # Repository configuration
+  tickets/
+    <ATLASSIAN_KEY>/
+      ticket.meta.json     # Ticket metadata (status, summary, etc.)
+      plan.md              # High-level plan and objectives
+      tasks.md             # Detailed task checklist
+      progress.log.md      # Append-only progress log
+      notes.md             # Free-form notes (user-editable)
+```
+
+### Configuration
+
+The `.ticket-mate/config.json` file contains:
+
+```json
+{
+  "jiraBaseUrl": "https://pamcms.atlassian.net",
+  "jiraProjectKey": "YOUR_PROJECT",
+  "jiraCloudId": "optional-cloud-id",
+  "defaultBranch": "main",
+  "integrations": {
+    "cursor": {
+      "enabled": true
+    },
+    "replit": {
+      "enabled": true,
+      "webhookUrl": "https://your-replit-webhook-url"
+    }
+  }
+}
+```
+
+### CLI Commands
+
+#### `tm init-repo`
+
+Initialize a repository for Ticket Mate integration:
+
+```bash
+tm init-repo --jira-base-url https://pamcms.atlassian.net --jira-project-key YOUR_PROJECT
+tm init-repo --enable-replit --replit-webhook-url https://your-webhook-url
+```
+
+Options:
+
+- `--jira-base-url <url>` - Jira base URL
+- `--jira-project-key <key>` - Jira project key
+- `--jira-cloud-id <id>` - Optional cloud ID
+- `--default-branch <branch>` - Default Git branch (default: main)
+- `--enable-replit` - Enable Replit integration
+- `--replit-webhook-url <url>` - Replit webhook URL
+- `--enable-cursor` - Enable Cursor integration
+
+#### `tm sync-tickets`
+
+Sync Jira issues into `.ticket-mate/tickets/`:
+
+```bash
+# Sync all tickets with default statuses
+tm sync-tickets
+
+# Sync specific statuses
+tm sync-tickets --status "Ready for Dev" --status "In Progress"
+
+# Limit number of tickets
+tm sync-tickets --limit 10
+
+# Dry run (show what would be created)
+tm sync-tickets --dry-run
+
+# Skip webhook notification
+tm sync-tickets --no-webhook
+```
+
+#### `tm status`
+
+Show status of tickets in `.ticket-mate/tickets/`:
+
+```bash
+# Show all tickets
+tm status
+
+# Filter by status
+tm status --filter-status "In Progress"
+
+# JSON output
+tm status --json
+```
+
+#### `tm emit-agent-instructions`
+
+Emit instructions for AI agents:
+
+```bash
+# Generic instructions
+tm emit-agent-instructions
+
+# Cursor-specific
+tm emit-agent-instructions --agent cursor
+
+# Replit-specific
+jm emit-agent-instructions --agent replit
+```
+
+### Replit Integration
+
+Ticket Mate can notify Replit automations when tickets are synced:
+
+1. **Create a Replit Automation** with a Custom Webhook Trigger
+2. **Copy the webhook URL** provided by Replit
+3. **Configure in `.ticket-mate/config.json`**:
+
+```json
+{
+  "integrations": {
+    "replit": {
+      "enabled": true,
+      "webhookUrl": "https://your-replit-webhook-url"
+    }
+  }
+}
+```
+
+4. **Run `tm sync-tickets`** - Ticket Mate will POST a JSON payload to the webhook:
+
+```json
+{
+  "event": "tickets_synced",
+  "projectKey": "YOUR_PROJECT",
+  "tickets": [
+    {
+      "key": "PROJ-123",
+      "status": "In Progress",
+      "summary": "Implement feature X",
+      "url": "https://pamcms.atlassian.net/browse/PROJ-123"
+    }
+  ],
+  "syncedAt": "2025-12-09T22:35:00.000Z"
+}
+```
+
+### Directory Structure (Multi-Project)
+
+The `.ticket-mate` directory uses a project-based structure:
+
+```
+.ticket-mate/
+  config.json              # Global configuration
+  projects/
+    <projectKey>/
+      project.meta.json    # Project metadata
+      tickets/
+        <ticketKey>/
+          ticket.meta.json # Ticket metadata
+          plan.md          # High-level plan
+          tasks.md         # Task checklist
+          progress.log.md  # Progress log
+          notes.md         # Free-form notes
+```
+
+Each project has its own folder, and tickets are organized within their project. This allows multiple Jira projects to coexist in the same repository.
+
+### Using with AI Agents
+
+AI agents (Cursor, Replit Agent, etc.) should:
+
+1. **Read ticket metadata** from `.ticket-mate/projects/<projectKey>/tickets/<ticketKey>/ticket.meta.json`
+2. **Follow the plan** in `.ticket-mate/projects/<projectKey>/tickets/<ticketKey>/plan.md`
+3. **Complete tasks** from `.ticket-mate/projects/<projectKey>/tickets/<ticketKey>/tasks.md`
+4. **Log progress** in `.ticket-mate/projects/<projectKey>/tickets/<ticketKey>/progress.log.md`
+5. **Commit changes** with the Jira key in the message (e.g., `feat(PROJ-123): ...`)
+
+Use `tm emit-agent-instructions --agent <agent>` to get specific instructions for your agent.
+
+### Admin UI
+
+Ticket Mate includes admin UI pages for browsing `.ticket-mate` content:
+
+- **`/admin/ticket-mate`** - Overview of all projects in `.ticket-mate`
+- **`/admin/ticket-mate/[projectKey]`** - Ticket list for a specific project
+- **`/admin/ticket-mate/[projectKey]/[ticketKey]`** - Detailed ticket view with plan, tasks, progress, and notes
+
+These pages read directly from the `.ticket-mate` filesystem structure and provide a read-only view of your tickets. All data is sourced from `.ticket-mate` on disk, not directly from Jira.
+
+### Best Practices
+
+- **Never delete** user-edited content in `plan.md`, `tasks.md`, or `notes.md`
+- **Always append** to `progress.log.md` (never overwrite)
+- **Check ticket status** before starting work (only work on "Ready for Dev" or "In Progress")
+- **Update task checklists** as you complete items
+- **Commit with Jira keys** in commit messages for traceability
+
+## API Integration
+
+The package includes a REST API server. Start it with:
+
+```bash
+npm run dev:server
+```
+
+#### Authentication
+
+All API routes require authentication via API key. Include it in requests:
+
+```bash
+# Using X-API-Key header
+curl -H "X-API-Key: your-api-key" http://localhost:3001/api/projects
+
+# Using Authorization header
+curl -H "Authorization: Bearer your-api-key" http://localhost:3001/api/projects
+```
+
+#### API Endpoints
+
+**Projects**
+
+- `GET /api/projects` - List all accessible Jira projects
+
+**Boards**
+
+- `GET /api/boards?projectKey=NOVA` - List boards for a project
+
+**Automation**
+
+- `POST /api/automation/tickets/from-bugs` - Create tickets from bugs-wip.json
+- `POST /api/automation/tickets/from-json` - Create tickets from JSON instructions
+- `POST /api/automation/bugs/sync-status` - Sync bug statuses from Jira
+- `GET /api/automation/bugs/statistics` - Get bug statistics
+- `POST /api/automation/bugs/fix-now` - Process "fix now" bug
+
+**Example Request**
+
+```bash
+curl -X POST http://localhost:3001/api/automation/tickets/from-bugs \
+  -H "X-API-Key: your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{"filePath": "public/bugs.json"}'
+```
+
+### Next.js Dashboard
+
+The package includes a Next.js dashboard that provides a web interface for:
+
+- Viewing all Jira projects
+- Expanding projects to see their boards
+- Direct links to Jira backlog for each board
+
+Start the dashboard:
+
+```bash
+npm run dev
+```
+
+The dashboard is available at `http://localhost:4000`.
+
+### Automation Features
+
+#### bugs-wip.json Format
+
+The automation system can process JSON files containing bug information:
+
+```json
+{
+  "bugs": [
+    {
+      "id": "bug-1",
+      "title": "Checkout button not working",
+      "category": "bug_report",
+      "status": "open",
+      "severity": "high",
+      "summary": "The checkout button does not respond when clicked",
+      "rootCause": "Event listener not attached",
+      "metadata": {
+        "jiraIssueKey": "NOVA-456",
+        "jiraIssueUrl": "https://.../browse/NOVA-456"
+      }
+    }
+  ]
+}
+```
+
+#### Status Flow
+
+Bugs go through these statuses:
+
+- `open` - New bug, needs ticket
+- `sending_to_jira` - Currently being sent to Jira
+- `sent_to_jira` - Ticket created in Jira
+- `fixed` - Bug is fixed
+- `resolved` - Bug is resolved
+- `closed` - Bug is closed
+- `unfixable` - Bug cannot be fixed
+- `fix now` - Priority bug, needs immediate attention
+
+#### Orchestrator Integration
+
+The package can process instructions directly from an orchestrator:
+
+```json
+{
+  "items": [
+    {
+      "id": "task-1",
+      "title": "Implement feature X",
+      "summary": "Add new feature",
+      "category": "feature_request",
+      "priority": "high"
+    }
+  ]
+}
+```
+
+## API Reference
+
+For detailed API documentation, see:
+
+- [API Reference](docs/api-reference.md)
+- [Automation Guide](docs/automation/AUTOMATION-GUIDE.md)
+- [Host Integration](docs/HOST-PROJECT-INTEGRATION.md)
+
+## Examples
+
+### Sync Tickets to Progress Files
+
+```typescript
+import { syncAll, getJiraConfig } from "@ameshkin/ticket-mate";
+
+const config = getJiraConfig();
+const result = await syncAll(config, {
+  baseDir: "./ticket-mate",
+  generateReports: true,
+  generateIndex: true,
+});
+
+console.log(`Synced ${result.ticketsSynced} tickets`);
+```
+
+### Create Jira Tickets from JSON
+
+```typescript
+import { processBugsJson } from "@ameshkin/ticket-mate";
+
+const result = await processBugsJson("public/bugs.json", {
+  projectKey: "NOVA",
+  issueType: "Bug",
+  epicKey: "NOVA-10",
+  labels: ["automated", "from-json"],
+});
+
+console.log(`Created ${result.created} tickets`);
+```
+
+### Generate AI Prompts
+
+```typescript
+import { buildTicketPrompts } from "@ameshkin/ticket-mate";
+
+const prompts = await buildTicketPrompts({
+  ticketKey: "NOVA-123",
+  markdownPath: ".orchestrator/epics/NOVA-10/NOVA-123.md",
+  repoRoot: process.cwd(),
+});
+
+console.log(prompts.systemPrompt);
+console.log(prompts.userPrompt);
+```
+
+### Create Board with AI Column
+
+```typescript
+import {
+  createCursorBoard,
+  ensureAiInProgressColumn,
+} from "@ameshkin/ticket-mate";
+
+const board = await createCursorBoard("NOVA", "Cursor Board");
+await ensureAiInProgressColumn(board.id);
+console.log(`Board created: ${board.name} (ID: ${board.id})`);
+```
+
+## Development
+
+### Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Run tests
+npm run test
+
+# Run type checking
+npm run typecheck
+
+# Start development server
+npm run dev
+
+# Start API server
+npm run dev:server
+
+# Start both
+npm run dev:all
+```
+
+### Project Structure
+
+```
+ticket-mate/
+├── src/
+│   ├── cli/              # CLI commands
+│   ├── client/           # Jira REST API client
+│   ├── config/           # Configuration management
+│   ├── sync/             # Ticket syncing
+│   ├── prompts/          # AI prompt generation
+│   ├── automation/       # Automation features
+│   ├── jira-management/  # Board, label, epic management
+│   └── server/           # REST API server
+├── app/                  # Next.js dashboard
+│   ├── api/              # Next.js API routes
+│   └── page.tsx          # Dashboard UI
+└── dist/                 # Built output
+```
+
+### Testing
+
+```bash
+# Run all tests
+npm run test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run with coverage
+npm run test:coverage
+
+# Run E2E tests
+npm run test:e2e
+```
+
+## Database Access
+
+### Prisma Studio (Cloud)
+
+Access the database via Prisma Studio Cloud:
+
+**Direct Link:**
+
+- [Prisma Studio Cloud](https://console.prisma.io/cmixzg6nk03vo2sflg2pzq64u/cmixzgvue03sd1efplmdnimkj/cmixzgvue03se1efpm49q18z0/studio#table=notifications&schema=public&view=table)
+
+**How to Access:**
+
+1. Click the link above or navigate to [Prisma Console](https://console.prisma.io)
+2. Log in with your Prisma account credentials
+3. Select the project: `ticket-mate`
+4. Navigate to the database you want to view
+5. Use the table browser to explore data
+
+**Note:** You must have access to the Prisma project to view the database. Contact the project owner if you need access.
+
+### Local Prisma Studio
+
+You can also run Prisma Studio locally to view and edit the database:
+
+```bash
+# Make sure DATABASE_URL is set in your .env file
+npx prisma studio
+```
+
+This will open Prisma Studio at `http://localhost:5555` where you can:
+
+- Browse all tables
+- View and edit records
+- Run queries
+- Export data
+
+**Prerequisites:**
+
+- `DATABASE_URL` must be configured in `.env`
+- Database must be accessible from your local machine
+- Prisma client must be generated: `npm run prisma:generate`
+
+### Database Schema
+
+The database schema is defined in `prisma/schema.prisma`. Key models include:
+
+- **User** - User accounts and authentication
+- **Account** - Tenant/organization accounts
+- **JiraCredential** - Per-user Jira OAuth credentials
+- **TokenUsage** - AI token usage tracking
+- **PlanTier** - Subscription plan tiers
+- **Project** - Jira project mappings
+- **IntegrationConnection** - Third-party integrations
+
+See `prisma/schema.prisma` for the complete schema definition.
+
+## License
+
+MIT
+
+## Author
+
+Amir Meshkin <amir.meshkin@gmail.com>