# Entity Query Commands

Reference for: `issues`, `mrs`, `notes`, `search`, `count`

---

## `issues` (alias: `issue`)

List or show issues from local database.

| Flag | Type | Default | Purpose |
|---|---|---|---|
| `[IID]` | positional | — | Omit to list, provide to show detail |
| `-n, --limit` | int | 50 | Max results |
| `--fields` | string | — | Select output columns (preset: `minimal`) |
| `-s, --state` | enum | — | `opened\|closed\|all` |
| `-p, --project` | string | — | Filter by project (fuzzy) |
| `-a, --author` | string | — | Filter by author username |
| `-A, --assignee` | string | — | Filter by assignee username |
| `-l, --label` | string[] | — | Filter by labels (AND logic, repeatable) |
| `-m, --milestone` | string | — | Filter by milestone title |
| `--status` | string[] | — | Filter by work-item status (COLLATE NOCASE, OR logic) |
| `--since` | duration/date | — | Filter by created date (`7d`, `2w`, `YYYY-MM-DD`) |
| `--due-before` | date | — | Filter by due date |
| `--has-due` | flag | — | Show only issues with due dates |
| `--sort` | enum | `updated` | `updated\|created\|iid` |
| `--asc` | flag | — | Sort ascending |
| `-o, --open` | flag | — | Open first match in browser |

**DB tables:** `issues`, `projects`, `issue_assignees`, `issue_labels`, `labels`
**Detail mode adds:** `discussions`, `notes`, `entity_references` (closing MRs)

### Robot Output (list mode)

```json
{
  "ok": true,
  "data": {
    "issues": [
      {
        "iid": 42, "title": "Fix auth", "state": "opened",
        "author_username": "jdoe", "labels": ["backend"],
        "assignees": ["jdoe"], "discussion_count": 3,
        "unresolved_count": 1, "created_at_iso": "...",
        "updated_at_iso": "...", "web_url": "...",
        "project_path": "group/repo",
        "status_name": "In progress"
      }
    ],
    "total_count": 150, "showing": 50
  },
  "meta": { "elapsed_ms": 40, "available_statuses": ["Open", "In progress", "Closed"] }
}
```

### Robot Output (detail mode — `issues <IID>`)

```json
{
  "ok": true,
  "data": {
    "id": 12345, "iid": 42, "title": "Fix auth",
    "description": "Full markdown body...",
    "state": "opened", "author_username": "jdoe",
    "created_at": "...", "updated_at": "...", "closed_at": null,
    "confidential": false, "web_url": "...", "project_path": "group/repo",
    "references_full": "group/repo#42",
    "labels": ["backend"], "assignees": ["jdoe"],
    "due_date": null, "milestone": null,
    "user_notes_count": 5, "merge_requests_count": 1,
    "closing_merge_requests": [
      { "iid": 99, "title": "Refactor auth", "state": "merged", "web_url": "..." }
    ],
    "discussions": [
      {
        "notes": [
          { "author_username": "jdoe", "body": "...", "created_at": "...", "is_system": false }
        ],
        "individual_note": false
      }
    ],
    "status_name": "In progress", "status_color": "#1068bf"
  }
}
```

**Minimal preset:** `iid`, `title`, `state`, `updated_at_iso`

---

## `mrs` (aliases: `mr`, `merge-request`, `merge-requests`)

List or show merge requests.

| Flag | Type | Default | Purpose |
|---|---|---|---|
| `[IID]` | positional | — | Omit to list, provide to show detail |
| `-n, --limit` | int | 50 | Max results |
| `--fields` | string | — | Select output columns (preset: `minimal`) |
| `-s, --state` | enum | — | `opened\|merged\|closed\|locked\|all` |
| `-p, --project` | string | — | Filter by project |
| `-a, --author` | string | — | Filter by author |
| `-A, --assignee` | string | — | Filter by assignee |
| `-r, --reviewer` | string | — | Filter by reviewer |
| `-l, --label` | string[] | — | Filter by labels (AND) |
| `--since` | duration/date | — | Filter by created date |
| `-d, --draft` | flag | — | Draft MRs only |
| `-D, --no-draft` | flag | — | Exclude drafts |
| `--target` | string | — | Filter by target branch |
| `--source` | string | — | Filter by source branch |
| `--sort` | enum | `updated` | `updated\|created\|iid` |
| `--asc` | flag | — | Sort ascending |
| `-o, --open` | flag | — | Open in browser |

**DB tables:** `merge_requests`, `projects`, `mr_reviewers`, `mr_labels`, `labels`, `mr_assignees`
**Detail mode adds:** `discussions`, `notes`, `mr_diffs`

### Robot Output (list mode)

```json
{
  "ok": true,
  "data": {
    "mrs": [
      {
        "iid": 99, "title": "Refactor auth", "state": "merged",
        "draft": false, "author_username": "jdoe",
        "source_branch": "feat/auth", "target_branch": "main",
        "labels": ["backend"], "assignees": ["jdoe"], "reviewers": ["reviewer"],
        "discussion_count": 5, "unresolved_count": 0,
        "created_at_iso": "...", "updated_at_iso": "...",
        "web_url": "...", "project_path": "group/repo"
      }
    ],
    "total_count": 500, "showing": 50
  }
}
```

### Robot Output (detail mode — `mrs <IID>`)

```json
{
  "ok": true,
  "data": {
    "id": 67890, "iid": 99, "title": "Refactor auth",
    "description": "Full markdown body...",
    "state": "merged", "draft": false, "author_username": "jdoe",
    "source_branch": "feat/auth", "target_branch": "main",
    "created_at": "...", "updated_at": "...",
    "merged_at": "...", "closed_at": null,
    "web_url": "...", "project_path": "group/repo",
    "labels": ["backend"], "assignees": ["jdoe"], "reviewers": ["reviewer"],
    "discussions": [
      {
        "notes": [
          {
            "author_username": "reviewer", "body": "...",
            "created_at": "...", "is_system": false,
            "position": { "new_path": "src/auth.rs", "new_line": 42 }
          }
        ],
        "individual_note": false
      }
    ]
  }
}
```

**Minimal preset:** `iid`, `title`, `state`, `updated_at_iso`

---

## `notes` (alias: `note`)

List discussion notes/comments with fine-grained filters.

| Flag | Type | Default | Purpose |
|---|---|---|---|
| `-n, --limit` | int | 50 | Max results |
| `--fields` | string | — | Preset: `minimal` |
| `-a, --author` | string | — | Filter by author |
| `--note-type` | enum | — | `DiffNote\|DiscussionNote` |
| `--contains` | string | — | Body text substring filter |
| `--note-id` | int | — | Internal note ID |
| `--gitlab-note-id` | int | — | GitLab note ID |
| `--discussion-id` | string | — | Discussion ID filter |
| `--include-system` | flag | — | Include system notes |
| `--for-issue` | int | — | Notes on specific issue (requires `-p`) |
| `--for-mr` | int | — | Notes on specific MR (requires `-p`) |
| `-p, --project` | string | — | Scope to project |
| `--since` | duration/date | — | Created after |
| `--until` | date | — | Created before (inclusive) |
| `--path` | string | — | File path filter (exact or prefix with `/`) |
| `--resolution` | enum | — | `any\|unresolved\|resolved` |
| `--sort` | enum | `created` | `created\|updated` |
| `--asc` | flag | — | Sort ascending |
| `--open` | flag | — | Open in browser |

**DB tables:** `notes`, `discussions`, `projects`, `issues`, `merge_requests`

### Robot Output

```json
{
  "ok": true,
  "data": {
    "notes": [
      {
        "id": 1234, "gitlab_id": 56789,
        "author_username": "reviewer", "body": "...",
        "note_type": "DiffNote", "is_system": false,
        "created_at_iso": "...", "updated_at_iso": "...",
        "position_new_path": "src/auth.rs", "position_new_line": 42,
        "resolvable": true, "resolved": false,
        "noteable_type": "MergeRequest", "parent_iid": 99,
        "parent_title": "Refactor auth", "project_path": "group/repo"
      }
    ],
    "total_count": 1000, "showing": 50
  }
}
```

**Minimal preset:** `id`, `author_username`, `body`, `created_at_iso`

---

## `search` (aliases: `find`, `query`)

Semantic + full-text search across indexed documents.

| Flag | Type | Default | Purpose |
|---|---|---|---|
| `<QUERY>` | positional | required | Search query string |
| `--mode` | enum | `hybrid` | `lexical\|hybrid\|semantic` |
| `--type` | enum | — | `issue\|mr\|discussion\|note` |
| `--author` | string | — | Filter by author |
| `-p, --project` | string | — | Scope to project |
| `--label` | string[] | — | Filter by labels (AND) |
| `--path` | string | — | File path filter |
| `--since` | duration/date | — | Created after |
| `--updated-since` | duration/date | — | Updated after |
| `-n, --limit` | int | 20 | Max results (max: 100) |
| `--fields` | string | — | Preset: `minimal` |
| `--explain` | flag | — | Show ranking breakdown |
| `--fts-mode` | enum | `safe` | `safe\|raw` |

**DB tables:** `documents`, `documents_fts` (FTS5), `embeddings` (vec0), `document_labels`, `document_paths`, `projects`

**Search modes:**
- **lexical** — FTS5 with BM25 ranking (fastest, no Ollama needed)
- **hybrid** — RRF combination of lexical + semantic (default)
- **semantic** — Vector similarity only (requires Ollama)

### Robot Output

```json
{
  "ok": true,
  "data": {
    "query": "authentication bug",
    "mode": "hybrid",
    "total_results": 15,
    "results": [
      {
        "document_id": 1234, "source_type": "issue",
        "title": "Fix SSO auth", "url": "...",
        "author": "jdoe", "project_path": "group/repo",
        "labels": ["auth"], "paths": ["src/auth/"],
        "snippet": "...matching text...",
        "score": 0.85,
        "explain": { "vector_rank": 2, "fts_rank": 1, "rrf_score": 0.85 }
      }
    ],
    "warnings": []
  }
}
```

**Minimal preset:** `document_id`, `title`, `source_type`, `score`

---

## `count`

Count entities in local database.

| Flag | Type | Default | Purpose |
|---|---|---|---|
| `<ENTITY>` | positional | required | `issues\|mrs\|discussions\|notes\|events\|references` |
| `-f, --for` | enum | — | Parent type: `issue\|mr` |

**DB tables:** Conditional aggregation on entity tables

### Robot Output

```json
{
  "ok": true,
  "data": {
    "entity": "merge_requests",
    "count": 1234,
    "system_excluded": 5000,
    "breakdown": { "opened": 100, "closed": 50, "merged": 1084 }
  }
}
```