# Jira Project Knowledge - Production Guide

This guide covers the setup, operation, and troubleshooting of the Jira Project Knowledge capability in Cowork Local.

## 1. Architecture Overview

Jira Project Knowledge enables Cowork to index Jira issues as searchable project knowledge. The flow is:

1.  **Configuration**: User maps a Cowork project to a Jira project key via UI.
2.  **Sync**: `JiraSyncService` fetches issues from Jira using the configured credentials.
3.  **Normalization**: Raw Jira JSON is converted to `CanonicalJiraIssue` (stripping markup, bounding content).
4.  **Indexing**: Canonical issues are stored as atomic JSON files in `~/.cowork_local/jira_kb/<project_id>/issues/`.
5.  **Retrieval**: `search_project_knowledge` MCP tool queries the local index using lexical scoring.

## 2. Prerequisites

*   **Jira Access**: Read-only access to the target Jira project.
*   **Credentials**:
    *   **Jira Cloud**: Email + API Token (from id.atlassian.com).
    *   **Jira Server/Data Center**: Personal Access Token (PAT) or Username/Password.
*   **Python**: 3.10+ (for Pydantic v2 compatibility).

## 3. Setup & Configuration

### 3.1 Connect Jira
1.  Open Cowork Local.
2.  Go to **Monitoring** -> **Tools** -> **Jira**.
3.  Enter **Base URL** (e.g., `https://your-domain.atlassian.net` or `https://jira.company.com`).
4.  Enter **Email** (for Cloud) or **Username** (for Server).
5.  Enter **API Token** or **PAT**.
6.  Click **Test Connection**.

### 3.2 Enable Project Knowledge
1.  In the same Jira dialog, check **Enable Jira Project Knowledge**.
2.  Enter **Project Mapping** in the format `cowork_project_id:JIRA_PROJECT_KEY`.
    *   Example: `proj-alpha:ALPHA, proj-beta:BETA`
    *   Click the **ⓘ** icon next to "Project Mapping" for detailed help on:
        *   **Project ID**: The Cowork project identifier (e.g., `cowork-local`). Find it in your current Cowork project settings.
        *   **Jira Key**: The Jira project key (e.g., `ALPHA` from issue `ALPHA-123`). Open any Jira issue to find it.
    *   **Common mistake**: Do not enter issue keys like `ABC-123`. Only enter the project key part `ABC`.
3.  Click **Save**.

### 3.3 Initial Sync
1.  Click **Sync Now**.
2.  Wait for the status to update to "Success: X issues synced".
3.  The sync runs in the background; the UI remains responsive.

## 4. Usage

### 4.1 Search via Agent
Ask the agent questions about the project requirements or bugs. The agent will automatically use `search_project_knowledge` if Jira Knowledge is enabled for the current project.

*   *Example*: "What are the acceptance criteria for the login feature?"
*   *Example*: "Find bugs related to database timeout."

### 4.2 MCP Tool
The tool `search_project_knowledge` is available via the Project Context MCP server.

*   **Input**: `project_id`, `query`, `top_k` (optional).
*   **Output**: Ranked list of excerpts with Jira source URLs.

## 5. Security & Isolation

*   **Read-Only**: The connector never writes to Jira.
*   **Project Isolation**: Knowledge is strictly scoped by `project_id`. A user with access to Project A cannot search Project B's knowledge, even if they guess the project ID. The target resolver enforces this structurally.
*   **Credential Safety**: Credentials are stored in the OS Keyring (via `SecretStore`), not in plain text config files (unless fallback is used). They are never logged or sent to the LLM.
*   **Untrusted Content**: Jira content is treated as untrusted. Prompt injection attempts in Jira descriptions are fenced and neutralized before reaching the agent context.

## 6. Observability

Sync operations emit audit events to `~/.cowork_local/audit/YYYY-MM-DD.jsonl`:

*   `jira_knowledge.sync.started`: Sync initiated.
*   `jira_knowledge.sync.completed`: Sync finished successfully (includes counts/duration).
*   `jira_knowledge.sync.failed`: Sync failed (includes error code).

## 7. Troubleshooting

### 403 Forbidden
*   **Cause**: Invalid credentials or insufficient permissions.
*   **Fix**:
    *   **Cloud**: Ensure you are using an API Token, not your password.
    *   **Server**: Ensure you are using a valid Personal Access Token (PAT). If PAT fails, try Basic Auth with your actual password (some older servers require this).
    *   Check that your user has "Browse Projects" permission for the target Jira project.

### "Jira Project Knowledge is not configured"
*   **Cause**: No project mapping found for the current identity.
*   **Fix**: Ensure the `cowork_project_id` in the mapping matches the project selected in Cowork.

### Sync Fails / Timeout
*   **Cause**: Network issues or large project size.
*   **Fix**: Check network connectivity to Jira. The sync has a timeout of 20s per request. For very large projects, the initial sync may take time; subsequent incremental syncs are faster.

## 8. File Structure

*   `~/.cowork_local/config.json`: Stores `jira` connection settings and `jira_knowledge` mappings.
*   `~/.cowork_local/jira_kb/<project_id>/issues/`: Indexed canonical issues (JSON).
*   `~/.cowork_local/jira_kb/<project_id>/manifest.json`: Sync state (last sync time, cursor).
*   `~/.cowork_local/audit/`: Audit logs.

## 9. Known Limitations

*   **Lexical Search**: Current retrieval uses term-overlap scoring, not semantic embeddings. It works well for exact terms and keywords but may miss conceptual synonyms.
*   **Manual Sync**: Incremental sync is not yet scheduled automatically; it must be triggered via "Sync Now" or CLI.
*   **Rich Text**: Complex Jira rich text (ADF) is simplified to plain text placeholders.