narai-primitives 2.1.2 → 2.2.0

package/plugins/github-connector/skills/github-connector/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: github-connector
+description: |
+  Use when the user asks about GitHub data or wants to act on GitHub —
+  repository info, code search, issue/PR/release/workflow inspection,
+  or any write that creates, updates, closes, or deletes a PR, issue,
+  comment, or release; merging PRs (admin); and managing Actions
+  workflow runs (rerun / cancel / dispatch).
+context: fork
+---
+
+# GitHub Connector
+
+Answer the user's question by invoking the `github-connector` binary
+exposed by this plugin. It delegates to `narai-primitives/github`
+via GitHub's REST v3 + GraphQL APIs.
+
+## Invocation
+
+```
+github-connector --action <action> --params '<json>'
+```
+
+Return the connector's JSON envelope verbatim.
+
+## Read actions
+
+| Action | Required params |
+|---|---|
+| `repo_info` | `owner`, `repo` |
+| `search_code` | `owner`, `repo`, `query`, optional `max_results` |
+| `get_issues` | `owner`, `repo`, optional `state`, `labels`, `max_results` |
+| `get_pulls` | `owner`, `repo`, optional `state`, `max_results` |
+| `get_pull_request` | `owner`, `repo`, `pull_number` |
+| `get_issue` | `owner`, `repo`, `issue_number` |
+| `get_file` | `owner`, `repo`, `path`, optional `ref` |
+| `get_issue_comments` | `owner`, `repo`, `issue_number` |
+| `get_pr_review_comments` | `owner`, `repo`, `pr_number` |
+| `list_release_assets` | `owner`, `repo`, `tag` |
+| `get_release_asset` | `owner`, `repo`, `asset_id` |
+| `list_workflow_runs` | `owner`, `repo`, optional `branch`/`event`/`status`/`head_sha` |
+| `get_workflow_run` | `owner`, `repo`, `run_id` |
+| `list_workflow_run_jobs` | `owner`, `repo`, `run_id` |
+| `get_workflow_run_logs` | `owner`, `repo`, `run_id` — returns redirect URL, not the ZIP body |
+
+## Write actions (escalate by default)
+
+| Action | Required params |
+|---|---|
+| `create_pull_request` | `owner`, `repo`, `title`, `head`, `base`, optional `body`/`draft` |
+| `update_pull_request` | `owner`, `repo`, `pull_number`, optional `title`/`body`/`base`/`state=open` |
+| `close_pull_request` | `owner`, `repo`, `pull_number` |
+| `create_issue` | `owner`, `repo`, `title`, optional `body`/`labels`/`assignees` |
+| `update_issue` | `owner`, `repo`, `issue_number`, optional `title`/`body`/`labels`/`state=open` |
+| `close_issue` | `owner`, `repo`, `issue_number`, optional `state_reason` |
+| `add_issue_comment` | `owner`, `repo`, `issue_number`, `body` |
+| `update_issue_comment` | `owner`, `repo`, `comment_id`, `body` |
+| `delete_issue_comment` | `owner`, `repo`, `comment_id` |
+| `add_pr_review_comment` | `owner`, `repo`, `pr_number`, `body`, `commit_id`, `path`, `line` |
+| `update_pr_review_comment` | `owner`, `repo`, `comment_id`, `body` |
+| `delete_pr_review_comment` | `owner`, `repo`, `comment_id` |
+| `create_release` | `owner`, `repo`, `tag_name`, optional `name`/`body`/`draft`/`prerelease` |
+| `update_release` | `owner`, `repo`, `release_id`, optional fields |
+| `delete_release` | `owner`, `repo`, `release_id` |
+| `delete_release_asset` | `owner`, `repo`, `asset_id` |
+| `rerun_workflow_run` | `owner`, `repo`, `run_id` |
+| `rerun_failed_jobs` | `owner`, `repo`, `run_id` |
+| `cancel_workflow_run` | `owner`, `repo`, `run_id` |
+| `trigger_workflow_dispatch` | `owner`, `repo`, `workflow_id_or_filename`, `ref`, optional `inputs` |
+
+## Admin actions (denied by default — operator must opt in)
+
+| Action | Required params |
+|---|---|
+| `merge_pull_request` | `owner`, `repo`, `pull_number`, `merge_method` ∈ {merge, squash, rebase} |
+
+To enable `merge_pull_request`, set `policy.admin: escalate` in
+`~/.github-agent/config.yaml` (or the repo-level overlay).
+
+## Credentials
+
+Set `GITHUB_TOKEN` to a PAT with:
+- `repo` — read + write on code, issues, PRs, comments, releases
+- `workflow` — required for `rerun_*`, `cancel_workflow_run`, and
+  `trigger_workflow_dispatch`
+
+## Config
+
+`~/.github-agent/config.yaml` (user-level) merges with
+`<cwd>/.github-agent/config.yaml` (repo overlay). Beyond the toolkit's
+standard `policy` and `approval_mode` keys, the connector reads:
+
+```yaml
+github:
+  require_draft_pr: true     # forces every create_pull_request to draft=true
+```
+
+This can be overridden at runtime by `GITHUB_REQUIRE_DRAFT_PR=1` (or 0).
+
+## Safety
+
+Every write call goes through the toolkit's policy gate. With no
+operator config, writes escalate (asking once), deletes escalate with a
+`delete` aspect for audit, and admin actions are denied until the
+operator explicitly opts in via YAML. The `delete` aspect is floored —
+operator config cannot downgrade it to `success`.

package/plugins/gitlab-connector/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "gitlab-connector-plugin",
+  "version": "1.0.0",
+  "description": "Read + write GitLab connector — projects, issues, merge requests, notes, releases, and CI pipelines. Policy-gated. Built on narai-primitives. Self-hosted GitLab supported via GITLAB_HOST.",
+  "author": "narailabs"
+}

package/plugins/gitlab-connector/README.md

@@ -0,0 +1,62 @@
+# gitlab-connector plugin
+
+Read and write GitLab data — project info, code search, issues,
+merge requests, notes, releases, and CI pipelines — through the
+narai-primitives connector toolkit's policy gate.
+
+## Credentials
+
+Set `GITLAB_TOKEN` to a PAT with `api` scope.
+
+| Scope | Why |
+|---|---|
+| `api` | Full read + write access to projects, issues, MRs, notes, releases, and pipelines |
+
+Tokens without `api` scope will see `AUTH_ERROR` with a scope hint
+when invoking any endpoint.
+
+Optional environment variables:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `GITLAB_HOST` | `https://gitlab.com` | Self-hosted GitLab base URL |
+| `GITLAB_NAMESPACE` | (none) | Default group/user namespace; omit when passing `namespace` explicitly per action |
+
+## Config
+
+Place YAML at `~/.gitlab-agent/config.yaml` (user-level) or
+`<cwd>/.gitlab-agent/config.yaml` (repo overlay). Repo overlay wins on
+collisions.
+
+```yaml
+policy:
+  read: success
+  write: escalate
+  admin: escalate              # enables merge_merge_request
+  aspects:
+    delete: escalate            # cannot be set to success — floored
+approval_mode: confirm_once
+gitlab:
+  require_draft_mr: true       # forces every create_merge_request to draft=true
+  host: https://gitlab.example.com   # self-hosted GitLab base URL (overrides GITLAB_HOST)
+```
+
+Runtime override: `GITLAB_REQUIRE_DRAFT_MR=1` forces drafts even when
+the YAML says false; `GITLAB_REQUIRE_DRAFT_MR=0` forces non-drafts.
+Invalid values throw at startup.
+
+## Action surface
+
+33 actions across reads (14), writes (18), and admin (1). See
+`skills/gitlab-connector/SKILL.md` for the full table.
+
+## Self-hosted GitLab
+
+Self-hosted GitLab >= 12.x (Bearer-auth PAT support) is supported. Set
+`GITLAB_HOST` or `gitlab.host` in config to your instance base URL,
+e.g. `https://gitlab.example.com`. The connector appends `/api/v4/` to
+all requests.
+
+## License
+
+See repo root.

package/plugins/{db-agent/bin/db-agent → gitlab-connector/bin/gitlab-connector}

@@ -2,14 +2,14 @@
 set -euo pipefail
 
 if [ -z "${CLAUDE_PLUGIN_DATA:-}" ]; then
-  echo "db-agent: CLAUDE_PLUGIN_DATA is not set (run from inside Claude Code)" >&2
+  echo "gitlab-connector: CLAUDE_PLUGIN_DATA is not set (run from inside Claude Code)" >&2
   exit 2
 fi
 
-CLI="${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/dist/connectors/db/cli.js"
+CLI="${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/dist/connectors/gitlab/cli.js"
 
 if [ ! -f "$CLI" ]; then
-  echo "db-agent: connector CLI not found at $CLI" >&2
+  echo "gitlab-connector: connector CLI not found at $CLI" >&2
   echo "Restart your Claude Code session to re-run the SessionStart install hook." >&2
   exit 2
 fi

package/plugins/gitlab-connector/commands/gitlab-connector.md

@@ -0,0 +1,6 @@
+---
+description: Run a GitLab action via the gitlab-connector connector
+argument-hint: "<action> <params-json>"
+---
+
+Invoke the `gitlab-connector` skill with the user's $ARGUMENTS as the action name and params JSON. Return the connector's JSON envelope verbatim.

package/plugins/gitlab-connector/hooks/hooks.json

@@ -0,0 +1,50 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (mkdir -p \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/\" && cd \"${CLAUDE_PLUGIN_DATA}\" && npm install --no-audit --no-fund) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" session-start"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" pre-tool-use"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" post-tool-use"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" session-end"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/gitlab-connector/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "gitlab-connector-plugin-runtime",
+  "version": "1.0.0",
+  "private": true,
+  "dependencies": {
+    "narai-primitives": "^2.1.3"
+  }
+}

package/plugins/gitlab-connector/plugin-config.json

@@ -0,0 +1,4 @@
+{
+  "name": "gitlab",
+  "binPath": "narai-primitives/dist/connectors/gitlab"
+}

package/plugins/gitlab-connector/skills/gitlab-connector/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: gitlab-connector
+description: |
+  Use when the user asks about GitLab data or wants to act on GitLab —
+  project info, code search, issue/MR/release/pipeline inspection,
+  or any write that creates, updates, closes, or deletes an MR, issue,
+  note, or release; merging MRs (admin); and managing CI pipeline runs
+  (retry / cancel / trigger / play_job).
+context: fork
+---
+
+# GitLab Connector
+
+Answer the user's question by invoking the `gitlab-connector` binary
+exposed by this plugin. It delegates to `narai-primitives/gitlab`
+via GitLab's REST API v4.
+
+## Invocation
+
+```
+gitlab-connector --action <action> --params '<json>'
+```
+
+Return the connector's JSON envelope verbatim.
+
+## Read actions
+
+| Action | Required params |
+|---|---|
+| `project_info` | `namespace`, `project` |
+| `search_code` | `namespace`, `project`, `query`, optional `max_results` |
+| `get_issues` | `namespace`, `project`, optional `state`, `max_results` |
+| `get_issue` | `namespace`, `project`, `iid` |
+| `get_merge_requests` | `namespace`, `project`, optional `state`, `max_results` |
+| `get_merge_request` | `namespace`, `project`, `iid` |
+| `get_file` | `namespace`, `project`, `path`, optional `ref` |
+| `get_notes` | `namespace`, `project`, `noteable_type` ∈ {issue, merge_request}, `noteable_iid` |
+| `list_release_links` | `namespace`, `project`, `tag` |
+| `get_release_link` | `namespace`, `project`, `tag`, `link_id` |
+| `list_pipelines` | `namespace`, `project`, optional `ref`, `status`, `max_results` |
+| `get_pipeline` | `namespace`, `project`, `pipeline_id` |
+| `list_pipeline_jobs` | `namespace`, `project`, `pipeline_id` |
+| `get_job_logs` | `namespace`, `project`, `job_id` |
+
+## Write actions (escalate by default)
+
+| Action | Required params |
+|---|---|
+| `create_merge_request` | `namespace`, `project`, `source_branch`, `target_branch`, `title`, optional `description`/`draft`/`assignee_ids`/`reviewer_ids`/`labels`/`milestone_id`/`remove_source_branch`/`squash` |
+| `update_merge_request` | `namespace`, `project`, `mr_iid`, optional `title`/`description`/`target_branch`/`state_event=reopen`/`assignee_ids`/`reviewer_ids`/`labels`/`milestone_id`/`remove_source_branch`/`squash` |
+| `close_merge_request` | `namespace`, `project`, `mr_iid` |
+| `create_issue` | `namespace`, `project`, `title`, optional `description`/`assignee_ids`/`labels`/`milestone_id`/`due_date` |
+| `update_issue` | `namespace`, `project`, `iid`, optional `title`/`description`/`assignee_ids`/`labels`/`milestone_id`/`due_date`/`state_event=reopen` |
+| `close_issue` | `namespace`, `project`, `iid` |
+| `add_note` | `namespace`, `project`, `noteable_type`, `noteable_iid`, `body`, optional `position` (MR diff comments only) |
+| `update_note` | `namespace`, `project`, `noteable_type`, `noteable_iid`, `note_id`, `body` |
+| `delete_note` | `namespace`, `project`, `noteable_type`, `noteable_iid`, `note_id` |
+| `create_release` | `namespace`, `project`, `tag_name`, `name`, optional `description`/`ref`/`assets` |
+| `update_release` | `namespace`, `project`, `tag_name`, optional `name`/`description`/`milestones` |
+| `delete_release` | `namespace`, `project`, `tag_name` |
+| `delete_release_link` | `namespace`, `project`, `tag_name`, `link_id` |
+| `retry_pipeline` | `namespace`, `project`, `pipeline_id` |
+| `retry_failed_jobs` | `namespace`, `project`, `pipeline_id` |
+| `cancel_pipeline` | `namespace`, `project`, `pipeline_id` |
+| `trigger_pipeline` | `namespace`, `project`, `token`, `ref`, optional `variables` |
+| `play_job` | `namespace`, `project`, `job_id`, optional `variables` |
+
+## Admin actions (denied by default — operator must opt in)
+
+| Action | Required params |
+|---|---|
+| `merge_merge_request` | `namespace`, `project`, `mr_iid`, optional `merge_commit_message`/`squash_commit_message`/`should_remove_source_branch`/`merge_when_pipeline_succeeds`/`sha`/`squash` |
+
+To enable `merge_merge_request`, set `policy.admin: escalate` in
+`~/.gitlab-agent/config.yaml` (or the repo-level overlay).
+
+## Credentials
+
+Set `GITLAB_TOKEN` to a PAT with:
+- `api` scope — required for all read + write + admin actions
+
+Optional:
+- `GITLAB_HOST` — self-hosted GitLab base URL (default: `https://gitlab.com`)
+- `GITLAB_NAMESPACE` — default group/user namespace; omit when passing `namespace` explicitly
+
+## Config
+
+`~/.gitlab-agent/config.yaml` (user-level) merges with
+`<cwd>/.gitlab-agent/config.yaml` (repo overlay). Beyond the toolkit's
+standard `policy` and `approval_mode` keys, the connector reads:
+
+```yaml
+policy:
+  read: success
+  write: escalate
+  admin: escalate              # enables merge_merge_request
+  aspects:
+    delete: escalate            # cannot be set to success — floored
+approval_mode: confirm_once
+gitlab:
+  require_draft_mr: true       # forces every create_merge_request to draft=true
+  host: https://gitlab.example.com   # self-hosted GitLab base URL
+```
+
+Runtime override: `GITLAB_REQUIRE_DRAFT_MR=1` forces drafts even when
+the YAML says false; `GITLAB_REQUIRE_DRAFT_MR=0` forces non-drafts.
+Invalid values throw at startup.
+
+## Safety
+
+Every write call goes through the toolkit's policy gate. With no
+operator config, writes escalate (asking once), deletes escalate with a
+`delete` aspect for audit, and admin actions are denied until the
+operator explicitly opts in via YAML. The `delete` aspect is floored —
+operator config cannot downgrade it to `success`.

package/plugins/jira-connector/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "jira-connector-plugin",
+  "version": "1.1.0",
+  "description": "Read + write CRUD on Jira issues, comments, transitions, and attachments. Policy-gated.",
+  "author": "narai"
+}

package/plugins/{jira-agent → jira-connector}/README.md

@@ -1,4 +1,4 @@
-# jira-agent-plugin
+# jira-connector-plugin
 
 Claude Code plugin wrapping `narai-primitives/jira`. Same layout as the other platform plugins.
 

package/plugins/{jira-agent/bin/jira-agent → jira-connector/bin/jira-connector}

@@ -2,14 +2,14 @@
 set -euo pipefail
 
 if [ -z "${CLAUDE_PLUGIN_DATA:-}" ]; then
-  echo "jira-agent: CLAUDE_PLUGIN_DATA is not set (run from inside Claude Code)" >&2
+  echo "jira-connector: CLAUDE_PLUGIN_DATA is not set (run from inside Claude Code)" >&2
   exit 2
 fi
 
 CLI="${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/dist/connectors/jira/cli.js"
 
 if [ ! -f "$CLI" ]; then
-  echo "jira-agent: connector CLI not found at $CLI" >&2
+  echo "jira-connector: connector CLI not found at $CLI" >&2
   echo "Restart your Claude Code session to re-run the SessionStart install hook." >&2
   exit 2
 fi

package/plugins/jira-connector/commands/jira-connector.md

@@ -0,0 +1,6 @@
+---
+description: Run a read-only Jira query via the jira-connector connector
+argument-hint: "<action> <params-json>"
+---
+
+Invoke the `jira-connector` skill with the user's $ARGUMENTS as the action name and params JSON. Return the connector's JSON envelope verbatim.

package/plugins/jira-connector/hooks/hooks.json

@@ -0,0 +1,50 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (mkdir -p \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/\" && cd \"${CLAUDE_PLUGIN_DATA}\" && npm install --no-audit --no-fund) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" session-start"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" pre-tool-use"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" post-tool-use"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_DATA}/node_modules/narai-primitives/plugin-hooks/dispatcher.mjs\" session-end"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/jira-connector/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "jira-connector-plugin-runtime",
+  "version": "1.0.0",
+  "private": true,
+  "dependencies": {
+    "narai-primitives": "^2.1.3"
+  }
+}

package/plugins/jira-connector/plugin-config.json

@@ -0,0 +1,4 @@
+{
+  "name": "jira",
+  "binPath": "narai-primitives/dist/connectors/jira"
+}

package/plugins/jira-connector/skills/jira-connector/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: jira-connector
+description: |
+  Use when the user asks about Jira data or wants to create, update, or
+  delete Jira content — JQL search, issue details, project metadata,
+  comments, attachments, status transitions, or any write operation on
+  issues and comments. Supports both read and write surfaces; every action
+  passes the policy gate before any network call is made: read actions
+  succeed by default, write and delete actions escalate by default,
+  privilege actions are hard-denied.
+context: fork
+---
+
+# Jira Connector
+
+Answer the user's question by invoking the `jira-connector` binary exposed by
+this plugin. It delegates to `narai-primitives/jira`, which enforces the
+policy gate before any Atlassian REST v3 call is made.
+
+## Invocation
+
+```
+jira-connector --action <action> --params '<json>'
+```
+
+Return the connector's JSON envelope verbatim.
+
+## Supported actions
+
+| Action              | Classification | Required params                                                              | Optional params                                                           |
+|---------------------|----------------|------------------------------------------------------------------------------|---------------------------------------------------------------------------|
+| `jql_search`        | read           | `jql`                                                                        | `max_results` (default 50, max 500)                                       |
+| `get_issue`         | read           | `issue_key` (e.g. `PROJ-123`)                                                | `expand` (array of field names)                                           |
+| `get_project`       | read           | `project_key` (e.g. `PROJ`)                                                  |                                                                           |
+| `list_attachments`  | read           | `issue_key`                                                                  |                                                                           |
+| `get_attachment`    | read           | `issue_key`, `attachment_id`                                                 |                                                                           |
+| `get_comments`      | read           | `issue_key`                                                                  | `max_results` (default 50)                                                |
+| `create_issue`      | write          | `project_key`, `issue_type`, `summary`                                       | `description` (content input), `labels`, `assignee_account_id`, `parent_key` |
+| `update_issue`      | write          | `issue_key`                                                                  | `summary`, `description` (content input), `labels`, `assignee_account_id` |
+| `delete_issue`      | write/delete   | `issue_key`                                                                  |                                                                           |
+| `add_comment`       | write          | `issue_key`, `body` (content input)                                          |                                                                           |
+| `update_comment`    | write          | `issue_key`, `comment_id`, `body` (content input)                            |                                                                           |
+| `delete_comment`    | write/delete   | `issue_key`, `comment_id`                                                    |                                                                           |
+| `transition_issue`  | write          | `issue_key`, `transition_id`                                                 | `comment` (content input)                                                 |
+| `post_attachment`   | write          | `issue_key`, `files` (array — see Multipart upload)                          |                                                                           |
+
+## Envelope shape
+
+**success**
+```json
+{"status": "success", "action": "create_issue", "data": {"key": "PROJ-123", "id": "10456", "self": "https://acme.atlassian.net/rest/api/3/issue/10456"}}
+```
+
+**escalate** (default for write/delete actions)
+```json
+{"status": "escalate", "action": "create_issue", "reason": "WRITE statements require approval"}
+```
+
+**denied** (default for privilege actions, or operator-set policy)
+```json
+{"status": "denied", "action": "delete_issue", "reason": "DELETE actions are not allowed by operator policy"}
+```
+
+**error**
+```json
+{"status": "error", "action": "create_issue", "error_code": "VALIDATION_ERROR", "message": "Invalid ADF: root.type must be 'doc'", "retriable": false}
+```
+
+## Content input (ADF / markdown / plain)
+
+Fields that accept body text (`description`, `body`, `comment`) use a
+discriminated union so you can pass whichever format is most convenient:
+
+**markdown** (converted via marklassian; output validated via assertValidAdf):
+```json
+{"description": {"format": "markdown", "value": "# Title\n\nSome **bold** text."}}
+```
+
+**ADF** (passed through; validated via assertValidAdf):
+```json
+{"description": {"format": "adf", "value": {"type": "doc", "version": 1, "content": []}}}
+```
+
+**plain** (wrapped in an ADF paragraph node):
+```json
+{"description": {"format": "plain", "value": "Just text."}}
+```
+
+## Multipart upload
+
+`post_attachment` uploads one or more files to an issue. Each entry in
+`files` is either inline base64 or a local path:
+
+```json
+{
+  "issue_key": "PROJ-1",
+  "files": [
+    {"filename": "report.pdf", "content_base64": "JVBERi..."},
+    {"path": "./uploads/screenshot.png"}
+  ]
+}
+```
+
+Path inputs must resolve under the current working directory (validated via
+the toolkit's `checkPathContainment`); any path that escapes CWD returns a
+`VALIDATION_ERROR` envelope without making any network call.
+
+## Credentials
+
+Set these environment variables before use:
+
+| Variable         | Description                                  |
+|------------------|----------------------------------------------|
+| `JIRA_SITE_URL`  | Your Atlassian site URL (e.g. `https://acme.atlassian.net`) |
+| `JIRA_EMAIL`     | Atlassian account email                      |
+| `JIRA_API_TOKEN` | Atlassian API token                          |
+
+Alternatively, register a credential provider via
+`narai-primitives/credentials`. Per-site credentials can be configured
+under `connectors.jira.options.sites.<alias>` in
+`~/.connectors/config.yaml`.
+
+## Safety
+
+Read AND write surface; the policy gate gates every action before any
+network call is made. WRITE escalates by default; DELETE also escalates by
+default; PRIVILEGE is hard-denied. Never bypass the `jira-connector` binary to
+call the Atlassian REST API directly — the binary is the only sanctioned
+channel. Never edit the operator's config to weaken a policy decision;
+report the decision instead.
+
+Default policy (operator may override under `connectors.jira.policy` in
+`~/.connectors/config.yaml`; per-site override under
+`connectors.jira.options.sites.<alias>.policy`):
+
+```yaml
+policy:
+  read: allow
+  write: escalate
+  delete: escalate
+  admin: deny
+  privilege: deny
+```
+
+The `admin` and `privilege` rules cannot be set to `allow` — the safety
+floor is enforced at config load.

package/plugins/linear-connector/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "linear-connector-plugin",
+  "version": "1.0.0",
+  "description": "Read + write CRUD on Linear issues, projects, comments, and attachment links. Policy-gated.",
+  "author": "narai"
+}