docs: document Jira TaskSpawner fields

[zerone0x]

What type of PR is this?

/kind docs

What this PR does / why we need it:

Documents the missing Jira TaskSpawner source fields in docs/reference.md so users can configure Jira without reading the API types.

Adds reference rows for:

• spec.when.jira.baseUrl
• spec.when.jira.project
• spec.when.jira.jql
• spec.when.jira.secretRef.name

Which issue(s) this PR is related to:

Fixes #1061
Also addresses part of #777

Special notes for your reviewer:

Kept this scoped to the field-level reference gap from #1061. Jira secret details already exist in docs/integration.md.

Does this PR introduce a user-facing change?

Document missing Jira TaskSpawner source fields in the API reference.

[cubic-dev-ai]

No issues found across 1 file

[greptile-apps]

Greptile Summary

This PR adds four missing Jira TaskSpawner source fields (baseUrl, project, jql, secretRef.name) to the API reference table. All field names, required/optional markings, and descriptions match the Jira struct in api/v1alpha1/taskspawner_types.go and the runtime behaviour in internal/source/jira.go.

Confidence Score: 5/5

Safe to merge; all new rows are factually correct and match the API types.

The only finding is a P2 style suggestion about documenting ORDER BY hoisting in the jql description. No logic errors, no missing fields, no inaccurate required/optional markings. P2-only findings do not reduce the score below 5.

No files require special attention.

Important Files Changed

Filename	Overview
docs/reference.md	Adds four accurate Jira field rows (baseUrl, project, jql, secretRef.name); jql description omits the ORDER BY hoisting behaviour that the implementation performs.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[spec.when.jira] --> B[baseUrl\nJira instance URL]
    A --> C[project\nProject key e.g. PROJ]
    A --> D[jql\nOptional JQL filter]
    A --> E[secretRef.name\nK8s Secret reference]
    A --> F[pollInterval\nPer-source override]

    D -->|empty| G["project = <project>"]
    D -->|set, no ORDER BY| H["project = <project> AND (<jql>)"]
    D -->|set, with ORDER BY| I["project = <project> AND (<filter>) ORDER BY ..."]

    E --> J[Secret read by spawner pod\nvia env vars at runtime]

    J --> L{user credential present?}
    L -->|Yes| M[Basic auth\nJira Cloud]
    L -->|No| N[Bearer token auth\nJira DC/Server PAT]

Loading

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
docs/reference.md:184
**JQL description omits ORDER BY handling**

The description states the full query is `project = <project> AND (<jql>)`, but when `jql` contains an `ORDER BY` clause, the implementation extracts it and places it outside the parentheses (e.g., `project = PROJ AND (status = Open) ORDER BY created DESC`). Without this note, a reader substituting their own JQL with `ORDER BY` into the documented pattern would produce invalid JQL (`project = PROJ AND (status = Open ORDER BY created DESC)`).

Consider clarifying, e.g.:

```suggestion
| `spec.when.jira.jql` | Optional JQL filter appended to the default query; when set, the full query is `project = <project> AND (<jql>)`. `ORDER BY` clauses are automatically hoisted outside the parentheses, so `jql: "status = Open ORDER BY created DESC"` produces `project = PROJ AND (status = Open) ORDER BY created DESC`. | No |
```

_{Reviews (1): Last reviewed commit: "docs: document Jira TaskSpawner fields" | Re-trigger Greptile}

[greptile-apps]

JQL description omits ORDER BY handling

The description states the full query is project = <project> AND (<jql>), but when jql contains an ORDER BY clause, the implementation extracts it and places it outside the parentheses (e.g., project = PROJ AND (status = Open) ORDER BY created DESC). Without this note, a reader substituting their own JQL with ORDER BY into the documented pattern would produce invalid JQL (project = PROJ AND (status = Open ORDER BY created DESC)).

Consider clarifying, e.g.:

Suggested change

	| `spec.when.jira.jql` | Optional JQL filter appended to the default query; when set, the full query is `project = <project> AND (<jql>)` | No |
	| `spec.when.jira.jql` | Optional JQL filter appended to the default query; when set, the full query is `project = <project> AND (<jql>)`. `ORDER BY` clauses are automatically hoisted outside the parentheses, so `jql: "status = Open ORDER BY created DESC"` produces `project = PROJ AND (status = Open) ORDER BY created DESC`. | No |

Prompt To Fix With AI

This is a comment left during a code review.
Path: docs/reference.md
Line: 184

Comment:
**JQL description omits ORDER BY handling**

The description states the full query is `project = <project> AND (<jql>)`, but when `jql` contains an `ORDER BY` clause, the implementation extracts it and places it outside the parentheses (e.g., `project = PROJ AND (status = Open) ORDER BY created DESC`). Without this note, a reader substituting their own JQL with `ORDER BY` into the documented pattern would produce invalid JQL (`project = PROJ AND (status = Open ORDER BY created DESC)`).

Consider clarifying, e.g.:

```suggestion
| `spec.when.jira.jql` | Optional JQL filter appended to the default query; when set, the full query is `project = <project> AND (<jql>)`. `ORDER BY` clauses are automatically hoisted outside the parentheses, so `jql: "status = Open ORDER BY created DESC"` produces `project = PROJ AND (status = Open) ORDER BY created DESC`. | No |
```

How can I resolve this? If you propose a fix, please make it concise.