@jini-ai/agent-plugins 0.6.16 → 0.6.19

package/github/skills/github/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: github
+description: Work against a GitHub repository through this workspace's own saved credentials — write and update files in one atomic commit, dispatch and follow a GitHub Actions run, read a failed run's logs, commit the site's rendered static export, back up the site itself to a private repository, deploy the host's server through its GitHub Actions deploy workflow — with no git, no gh CLI, and no token ever passing through the assistant. Encodes the rules generic GitHub knowledge gets wrong here: a 204 dispatch means queued and never deployed, a workflow only fires on the branch its own trigger names, a repository secret is always the human's step, a 403 on an org-wide listing is a normal app-scoped-token boundary rather than a broken credential, and editing an existing file means diffing the MODIFIED files and not only the added and deleted ones.
+---
+
+# GitHub, through the site's saved credentials
+
+## Connection card
+
+Choose the card yourself from its `usedFor` list. Reuse a saved key or working sign-in for that
+task. Never offer a replacement unless the person asks.
+
+Open **Connect GitHub** with `credential_save {kind:"plugin-provider",target:"github"}`; it saves the API credential labelled `github`. For `github-source-control`, use `credential_save {kind:"plugin-provider",target:"github-source-control"}`; it saves through the source-control owner. For Pages hosting use the `github-pages` plugin’s card. These remain distinct save contracts. Each card names the repository permissions and links to fine-grained token creation. Never collect a token in chat.
+
+## Scope
+
+This plugin owns **GitHub**: repositories, commits, branches, Actions, and the token and permission
+semantics behind all of them. It owns nothing else.
+
+It knows nothing about where a build is *deployed to*. Fly, Render, Railway, a container registry,
+a VPS — none of that is here, and a rule that only makes sense for one host does not belong here.
+A host-specific procedure (the bundled `fly` plugin's server deploy is the one that ships
+today) is expected to describe its own hosting rules and then hand the GitHub half to this
+document. That split is deliberate: every
+skill of every enabled plugin reaches the assistant's prompt at the same time, so the same rule
+written twice, slightly differently, becomes a contradiction rather than emphasis.
+
+---
+
+## Which job is this? Source control or a deploy
+
+Decide this first; the two jobs use different tools.
+
+- **Source control and backup** — write files into a repository, commit the site's rendered export,
+  back up the site, or start and follow any other workflow: the tools in the rest of this document.
+- **Deploying the host's server with GitHub Actions** — use the deployment tools with platform
+  `github-actions`, never a hand-built dispatch. Call `deployment_ops_deploy` with target
+  `owner/repo` and the branch or tag. It resolves the ref to a full SHA and dispatches the host's
+  deploy workflow pinned to that commit; the host guidance describes that workflow's own inputs and
+  refusals. Say which commit will build. A started deploy is queued, never deployed: follow it with
+  `deployment_ops_wait` (pass the returned runId) until `finished`, then check the live site. Use
+  `deployment_ops_status` and `deployment_ops_logs` to find a failed job and step. Never retry a
+  deploy whose connection dropped before checking `deployment_ops_status`. The saved
+  `api.github.com` credential needs Actions write. Setting up the server host itself (its config,
+  volume and secrets) is the host plugin's job, not this one's.
+
+---
+
+## What you are allowed to use, and what does not exist here
+
+Two native host tools do everything below. **This plugin ships no MCP server and adds no tool.**
+Its deploy half is only the `github-actions` platform behind the core `deployment_ops_*` tools.
+
+| Tool | What it is |
+|---|---|
+| `custom_credential_make_request` | One authenticated `GET`/`POST`/`PUT`/`PATCH`/`DELETE` to GitHub's REST API through a saved credential. You pass a `label` and a **full absolute URL**; the server injects the real `Authorization` header. |
+| `custom_credential_write_files` | A human-confirmed, atomic write of 1–25 named files onto an **existing** branch (blob → tree → commit → non-force ref update). |
+
+Two more exist for a narrower job — `source_control_get_capabilities` and
+`source_control_execute_commit` — and they are **not** general-purpose repo writes. See
+`references/source-control.md` before you reach for either; the distinction between them and
+`custom_credential_write_files` is the single easiest thing to get wrong in this document.
+
+And two back up the site itself — `site_backup_plan`, then `site_backup_push` — into a private
+repository. See `references/site-backup.md`.
+
+There is no `git`, no `gh`, and no shell path. **Never shell out to `curl`, `wget`, or `git` to
+talk to GitHub.** A raw shell request bypasses the saved-credential store entirely and either
+fails outright or forces a token into your context to make it work — which is exactly the thing
+the store exists to prevent.
+
+### You do not choose the host
+
+`custom_credential_make_request` refuses any URL whose host is not on that credential's own saved
+allowlist (its base URL plus any saved additional hosts), **before any request is sent**. This is
+not a limitation to route around. It is the property that makes an agent-held credential safe at
+all: the human decided, once, at save time, which origins this token may ever reach.
+
+So: build every URL from `https://api.github.com` (or whatever base the credential actually
+saved — GitHub Enterprise has its own). If a call is refused, the error names the hosts that
+*are* allowed. Read it and use one; do not try a different host to see what sticks.
+
+To find the label, call `content_read.custom_credential` with `{}`. It returns each saved
+credential's label, category, base URL and additional hosts — never a token. A workspace with a
+credential labelled `github` is the expected case, but do not assume the label: read it.
+
+---
+
+## The rules
+
+These are the reason this plugin exists. Each one has cost a real debugging session.
+
+### Rule 1 — A repository secret is ALWAYS the human's step. This is not negotiable.
+
+Creating or updating a GitHub Actions secret through the API requires encrypting the value against
+the repository's own public key. To do that, **the secret value would have to pass through your
+context** — you would have to hold the plaintext token in order to encrypt it.
+
+That is not an inconvenience on the way to a shortcut. **It is the failure mode.** The entire
+saved-credential design exists so a secret never reaches the assistant, and a step that requires
+holding one is a step the assistant does not perform, no matter how much friction it saves.
+
+So you never call `PUT /repos/{owner}/{repo}/actions/secrets/{name}`, you never fetch
+`.../actions/secrets/public-key` in order to encrypt something, and you never ask a human to paste
+a token into the chat so you can do it for them. You hand them the exact instruction instead:
+
+> Go to **Settings → Secrets and variables → Actions → New repository secret** in
+> `<owner>/<repo>`. Name it exactly `<SECRET_NAME>`. Paste only the value — do not commit it
+> anywhere, and do not paste it into this chat.
+
+Then **wait for them to confirm.** Do not dispatch a workflow that needs a secret before they have
+said it is set: the run fails on the runner in a way that reads like a config problem rather than a
+missing secret, and you will debug the wrong thing.
+
+The same rule covers environment secrets, organization secrets, and Dependabot secrets. Reading
+which secret *names* exist (`GET .../actions/secrets`) is fine — GitHub never returns a value — and
+is a genuinely useful way to confirm a human's "I set it" without asking twice.
+
+### Rule 2 — A 204 from a workflow dispatch means QUEUED. It does not mean anything ran.
+
+`POST /repos/{owner}/{repo}/actions/workflows/{file}/dispatches` returns **204 with an empty body**
+on success. All that 204 asserts is that GitHub accepted the request.
+
+Nothing has built. Nothing has deployed. Nothing has even started — the run may not appear in the
+runs list for a second or two, and it may sit `queued` behind another run after that.
+
+**Never report success at the dispatch.** Report "queued", then follow the run
+(`references/actions.md` has the poll loop and how to read a failure). Say what you actually
+observed, at the stage you observed it.
+
+### Rule 3 — A workflow only fires on the branch its own trigger names.
+
+A workflow's `on: push:` names branches. A push to any other branch does **nothing** — no run, no
+error, no warning. The same is true of `workflow_dispatch`: the `ref` you dispatch against must be
+a branch the workflow file exists on, and GitHub reads the workflow definition *from that ref*.
+
+Two failure shapes follow, and both look like "the workflow is broken":
+
+- You wrote the workflow onto a branch its own `push:` trigger does not list, pushed, and nothing
+  happened. Nothing is broken; the trigger simply did not match.
+- You dispatched against a `ref` where the workflow file does not exist yet. GitHub returns
+  **422**, not 404, and the message is about the workflow rather than the ref.
+
+So before you push or dispatch: read the workflow's own trigger, and name the branch explicitly.
+Never assume `main`; a repository's default branch is a fact to look up
+(`GET /repos/{owner}/{repo}` → `default_branch`), not a convention to rely on.
+
+### Rule 4 — When you EDIT an existing file, diff the MODIFIED files. Not just added and deleted.
+
+This one has already cost two silent production failures.
+
+A history force-push once rewrote a workflow file and dropped two `--build-arg` flags from it. A
+review that looked at which files were **added** and which were **deleted** saw nothing wrong —
+the file was neither. It was modified, and the modification quietly removed two load-bearing lines.
+Two deploys failed before anyone connected the two facts.
+
+`custom_credential_write_files` replaces a file's **entire content**; it does not patch. So when
+you are updating a file that already exists:
+
+1. Read the current content first (`GET /repos/{owner}/{repo}/contents/{path}?ref={branch}`,
+   which returns base64, or the raw blob via the Git Data API).
+2. Produce the new content from what is actually there — never from memory, and never from a
+   template you assume matches.
+3. Before writing, state what changed, **line by line, including every line you removed.**
+
+The confirmation dialog names each path as a create or an update, resolved against the branch's
+real current state. An "update" label is your cue that a full-content replacement is about to
+happen and that everything you did not carry forward is about to be gone.
+
+### Rule 5 — A 403 on an org-wide or account-wide listing is a permission BOUNDARY, not a broken credential.
+
+Many real tokens are scoped to a single repository or a single app. Such a token can fully manage
+its own resource and still **403 on any call that enumerates an organization or an account** — the
+org's repositories, the account's installations, every-app-in-the-org listings.
+
+That 403 looks *exactly* like an expired, revoked, or wrong-scoped credential. It is neither.
+Misreading it once cost a full debugging session and nearly caused a working credential to be
+replaced.
+
+The rule: **prefer per-resource endpoints over listings.** If you know the `owner/repo`, ask about
+that repository directly. Resolve the identifier from the human, from a file already in the repo,
+or from the conversation — never by listing the org and searching it. If you genuinely have no
+identifier, ask; a question costs one turn, a wrong diagnosis costs a session.
+
+If a call does come back 401 or 403, **read the `authDiagnostic` field on the result before
+reporting a bare failure**, follow the remedy it names, and retry at most **once**. There is
+deliberately no diagnostic hint on a 403 at all — 403 covers scopes, policy, and missing headers,
+so any guess would be a false lead. Report the failure and GitHub's own message plainly.
+
+### Rule 6 — Never print, echo, or reconstruct a secret.
+
+Not in a file you write, not in a commit message, not in a summary of what the human just did, not
+"redacted" with the first four characters showing. If a secret value must exist, the human types
+it — into GitHub's own secret form, or into the host's credential form's masked field.
+
+Nothing in this plugin's procedures requires you to see one, which is what makes this rule cheap to
+keep.
+
+---
+
+## Choosing the right tool
+
+Answer one question first: **is this app source, or is it the site's rendered output?**
+
+| You want to… | Use |
+|---|---|
+| Add or update named files — a config file, a workflow, a script, a Dockerfile | `custom_credential_write_files` |
+| Read anything at all from GitHub | `custom_credential_make_request` (`GET`) |
+| Deploy the host's server through its deploy workflow | `deployment_ops_deploy` with platform `github-actions` — see "Which job is this?" above |
+| Start any other workflow, or follow a run | `custom_credential_make_request` — see `references/actions.md` |
+| Back up the **site itself** (database, media, themes, plugins, settings) into a private repo | `site_backup_plan`, then `site_backup_push` — see `references/site-backup.md` |
+| Publish the **site's rendered static export** into a repo | `source_control_execute_commit` — see `references/source-control.md` |
+
+Conflating the last row with the rest wastes real work. `source_control_execute_commit` runs a
+fresh static export of the site and commits the resulting HTML and assets, and it **deletes** paths
+it previously wrote that the export no longer produces. It is a publishing target, not a way to put
+a file in a repository. A container build needs app source, and a rendered export is not app
+source — a build fed the wrong one either fails or, worse, succeeds and ships a site with no
+server. `references/source-control.md` states the difference in full; read it before you use
+either tool for the first time in a task.
+
+---
+
+## Reporting rules
+
+- **Report the stage you actually reached.** Queued is queued. Confirmed-but-unrun is not written.
+- **Name the branch, the repository, and the commit** in your result. A commit SHA and URL come
+  back from a successful write; use them rather than describing what you believe happened.
+- **A declined confirmation is a real outcome, not an error.** Say the human declined and stop.
+  Do not re-raise the dialog to see if they change their mind.
+- **Never re-dispatch on a hunch.** A second run queued behind a broken one wastes the human's
+  time and tells you nothing new.
+- **Say what you left unverified.** A value you guessed, a branch you assumed, a placeholder you
+  did not replace — each is a thing the human needs to know, not a detail.
+
+## References
+
+- `references/repo-files.md` — writing and updating files: the confirmation dialog, the limits,
+  every refusal reason, the workflow-path warning, and the read-then-replace procedure for edits.
+- `references/actions.md` — dispatching a workflow, polling a run, reading a failed run's logs,
+  and telling the distinct failure signatures apart.
+- `references/auth-and-tokens.md` — what a saved GitHub credential can and cannot do, scopes,
+  `authDiagnostic`, rate limits, and why repository secrets are the human's step.
+- `references/source-control.md` — `source_control_execute_commit` versus
+  `custom_credential_write_files`: two different credential stores, two different jobs, and the
+  app-source-versus-rendered-export distinction.
+- `references/site-backup.md` — backing up the site itself: plan then push, private repositories
+  only, what the dialog shows, the limits, every code and what to tell the human, and why a refused
+  push is planned again rather than forced.

package/github/skills/github/references/actions.md

@@ -0,0 +1,224 @@
+# GitHub Actions: dispatch, follow, diagnose
+
+Everything here goes through `custom_credential_make_request` against the saved GitHub credential.
+Nothing here needs a new tool, and nothing here needs a shell.
+
+---
+
+## Before you dispatch anything
+
+Three facts, none of which you may guess:
+
+1. **The repository** — `owner/repo`, exactly.
+2. **The workflow** — its filename (`deploy.yml`) or its numeric id. The filename is what a human
+   recognizes, so prefer it.
+3. **The ref** — the branch to run on. GitHub reads the workflow definition *from that ref*, so the
+   workflow file must already exist there. `GET /repos/{owner}/{repo}` returns `default_branch` if
+   you need it; do not assume `main`. And naming the ref is not knowing it — resolve it to a commit
+   before you dispatch, per the section below.
+
+And one check worth its single call: confirm the workflow is actually registered.
+
+```
+custom_credential_make_request({
+  label: "github",
+  method: "GET",
+  url: "https://api.github.com/repos/<owner>/<repo>/actions/workflows"
+})
+```
+
+Each entry carries `id`, `name`, `path`, and `state`. A workflow whose `state` is
+`disabled_manually` or `disabled_inactivity` accepts a dispatch and then never runs — worth
+catching here rather than in a confused poll loop ten minutes later.
+
+If a file you just wrote is not in that list, GitHub has not picked it up yet, or it is not on the
+ref you are looking at. Do not dispatch into that gap.
+
+---
+
+## Resolve the ref to a commit, and say which commit, before you dispatch
+
+**A branch name is not a commit.** `main` reads as the same string on the day your work lands on it
+and on a day it is a month behind — the name cannot tell those two apart, and neither can the human,
+unless you tell them. One GET turns the name into a fact:
+
+```
+custom_credential_make_request({
+  label: "github",
+  method: "GET",
+  url: "https://api.github.com/repos/<owner>/<repo>/branches/<ref>"
+})
+```
+
+Three fields off that response:
+
+| Field | What it gives you |
+|---|---|
+| `name` | The ref, confirmed to exist. A 404 here is the same missing ref the dispatch would have returned as a **422**, caught one call earlier and in a message that names it plainly. |
+| `commit.sha` | The exact commit this run will build. |
+| `commit.commit.committer.date` | When that commit landed on the ref. |
+
+**State all three before you POST the dispatch**, with the age in plain words:
+
+> Deploying `main` @ `f2997c6e` — committed 2026-09-11, 7 days ago.
+
+The date is the half that does the work. A tip a week old, told to someone who has been working all
+week, is the visible shape of *"this is about to ship something other than what you just wrote"* —
+and it is one line, at the only moment it is still cheap.
+
+**This step reports. It never blocks.** Say what the ref resolves to, then dispatch. Do not ask for
+confirmation, do not refuse, and do not wait to be told to continue. Whether this deploy should go
+out is the human's call, and they can only make it if you have said what it is.
+
+### One more comparison, already paid for
+
+The runs list you will poll *after* the dispatch also answers a question worth asking *before* it:
+
+```
+custom_credential_make_request({
+  label: "github",
+  method: "GET",
+  url: "https://api.github.com/repos/<owner>/<repo>/actions/workflows/<file.yml>/runs?per_page=1"
+})
+```
+
+If `workflow_runs[0].head_sha` equals the `commit.sha` you just resolved, this run will build
+**byte-identical source to the last one**. Say so, in those words, before you dispatch. A green run
+that changes nothing is the most confusing outcome anything in this document can produce, and it is
+fully predictable one call ahead of it happening.
+
+### What you cannot compare against
+
+The human's own working copy. There is no `git` and no shell here — their local branch, their
+uncommitted work, and whether they have pushed any of it are all invisible to you. Do not guess at
+them, and do not imply you checked. Give them the ref, the SHA and its date; if that tip reads older
+than the conversation you are having, say the date out loud and let them draw the conclusion.
+
+---
+
+## Dispatch
+
+```
+custom_credential_make_request({
+  label: "github",
+  method: "POST",
+  url: "https://api.github.com/repos/<owner>/<repo>/actions/workflows/<file.yml>/dispatches",
+  headers: { "Accept": "application/vnd.github+json", "Content-Type": "application/json" },
+  body: "{\"ref\":\"<branch>\"}"
+})
+```
+
+**Success is 204 with an empty body, and 204 means QUEUED.** Not built, not deployed, not started.
+This is the single most reported-wrong result in this whole document. Say "queued", then follow it.
+
+The failures you will actually see, and what each one means:
+
+| Status | What it actually is |
+|---|---|
+| **404** | The workflow file does not exist at that path — *or* the token cannot see this repository at all. Both look identical here. Confirm the repo with `GET /repos/{owner}/{repo}` before you assume the path is wrong. |
+| **422** | The workflow exists but has no `workflow_dispatch` trigger, or the `ref` you named does not exist. GitHub's message names which; read it rather than retrying. |
+| **403** | Usually the token lacks Actions write. Occasionally an org policy. See `auth-and-tokens.md`. |
+
+Never retry a 422 with a different guess. Fix the actual cause.
+
+---
+
+## Follow the run
+
+There is no callback and no webhook here. You poll.
+
+```
+custom_credential_make_request({
+  label: "github",
+  method: "GET",
+  url: "https://api.github.com/repos/<owner>/<repo>/actions/workflows/<file.yml>/runs?per_page=1"
+})
+```
+
+Read `workflow_runs[0]`: `id`, `status`, `conclusion`, `html_url`, `head_branch`, `head_sha`,
+`created_at`. `head_sha` is the commit that actually built: check it against the SHA you resolved
+before dispatching, and report it next to the conclusion. The two differ when someone pushed
+between your read and your dispatch — a fact to state, not a problem to solve.
+
+**Two things to get right before you interpret it:**
+
+- The newest run may not be yours. Check `created_at` against when you dispatched, and check
+  `head_branch`. Reporting on someone else's run is worse than reporting nothing.
+- `status` and `conclusion` are different fields. `status` is `queued` / `in_progress` /
+  `completed`. `conclusion` is `null` until `status` is `completed`, and only then is it
+  `success` / `failure` / `cancelled` / `timed_out` / `skipped` / `action_required`.
+
+**A run sitting in `queued` is not stuck.** A concurrency group that queues rather than cancels
+will hold a run behind another one for as long as that one takes. Say "queued behind an earlier
+run" — do not diagnose a hang, and do not dispatch a second run to "get things moving": that
+lengthens the queue you are complaining about.
+
+Poll a handful of times with a real gap between calls, and report what you actually see each time.
+If it is still running when you run out of patience, say so and give the human `html_url`. An
+honest "still in progress after N checks, here is the link" is a better answer than a guess.
+
+---
+
+## When a run fails
+
+Do not report "the workflow failed" and stop. Find the step.
+
+```
+custom_credential_make_request({
+  label: "github",
+  method: "GET",
+  url: "https://api.github.com/repos/<owner>/<repo>/actions/runs/<run_id>/jobs"
+})
+```
+
+Each job carries `name`, `status`, `conclusion`, and a `steps` array where every step has its own
+`name`, `number`, and `conclusion`. **The first step whose `conclusion` is `failure` is the
+answer** — everything after it is `skipped`, and reporting a skipped step as the failure sends the
+human to the wrong place.
+
+Report: the job name, the step name and number, and the run's `html_url`.
+
+### The raw-logs endpoint does not work from here, and that is by design
+
+`GET /repos/{owner}/{repo}/actions/jobs/{job_id}/logs` does not return logs. It returns a **302**
+whose `Location` points at an object-store host.
+
+`custom_credential_make_request` follows **zero** redirects, and that object-store host is not on
+the credential's saved allowlist, so you cannot follow it either. You will see the 302 and its
+`Location` header, and that is where it ends. This is not a bug to work around — following an
+arbitrary redirect target with a credential attached is exactly the egress hazard the single-hop
+policy exists to close.
+
+So the honest procedure is:
+
+1. Get the failing job and step from the `/jobs` response above. That is genuinely most of what a
+   log would tell you.
+2. Give the human the run's `html_url` and name the failing step, so one click lands them on it.
+3. If the actual log text matters, **ask them to paste the relevant lines.** Do not claim you read
+   logs you did not read.
+
+### Telling failure signatures apart
+
+These four are the ones that get confused with each other, and each needs a different next move:
+
+| Signature | What it means | What to do |
+|---|---|---|
+| The run never appears | The trigger did not match, or the file is not on that ref | Re-read the workflow's own `on:` block and the ref you pushed to. Do not re-dispatch. |
+| Fails immediately, in the first seconds, on a setup or auth step | A missing or wrong repository secret | Confirm with the human that the secret is set, by exact name. `GET .../actions/secrets` lists names (never values). |
+| Fails mid-run in a build or deploy step | A real error in the thing being built or shipped | Name the step and hand over the run URL. This is not a GitHub problem. |
+| `conclusion: "action_required"` | Waiting on a human — an approval, or a first-time contributor gate | Tell the human it is waiting on them, and where. Nothing you can do moves it. |
+
+A cancelled run and a timed-out run are also distinct from a failure, and both are commonly a
+human's or a queue's doing rather than a defect. Read `conclusion` before you write the word
+"failed".
+
+---
+
+## Rate limits
+
+Every response carries `x-ratelimit-remaining` and `x-ratelimit-reset`. A **403 with
+`x-ratelimit-remaining: 0`** is a rate limit, not a permission problem — and telling a human their
+token is broken when they are merely throttled is a real, avoidable mistake.
+
+Polling is the only thing here that makes a meaningful number of calls, which is the practical
+argument for a real gap between polls rather than a tight loop.

package/github/skills/github/references/auth-and-tokens.md

@@ -0,0 +1,140 @@
+# Tokens, scopes, and permission boundaries
+
+## Where the token lives, and why you never see it
+
+Open `credential_save {kind:"plugin-provider",target:"github"}` for the plugin’s own GitHub card. It saves label `github` and base URL `https://api.github.com`, with the token sealed server-side. Existing rows can still be rotated by their exact saved label.
+
+You name the **label**. The server resolves the credential and injects the real `Authorization`
+header itself. The token never appears in a tool's input, in a tool's output, or anywhere in your
+context.
+
+To discover what is saved, call `content_read.custom_credential` with `{}`. It returns
+each credential's label, category, base URL, and additional hosts — never a token, and never a
+saved username. An empty list is the signal to ask a human to save one, not to look for another
+way in.
+
+Two headers you must never set on `custom_credential_make_request`: `Authorization` and `Cookie`
+(also `Host` and `Proxy-Authorization`). The server injects the real one, and a call trying to set
+any of these is refused.
+
+---
+
+## The host allowlist is a feature
+
+Every URL you pass must have a host on that credential's own saved list — its base URL plus any
+saved additional hosts. Anything else is refused **before any request is sent**, and the error
+names which hosts *are* allowed.
+
+This is the property that makes an agent-held credential safe: the human decided once, at save
+time, which origins this token may ever reach. Do not try alternate hosts to find one that works.
+Read the error, use a named host, or ask.
+
+The same policy follows **zero redirects**. A GitHub endpoint that answers with a 302 to an
+object-store host (the Actions job-logs endpoint is the one you will actually hit) simply ends
+there. See `actions.md`.
+
+---
+
+## Repository secrets are the human's step. Always.
+
+Writing a GitHub Actions secret through the API requires encrypting the value against the
+repository's public key — which requires **holding the plaintext value**, in your context, to
+encrypt it.
+
+That is the failure mode the entire credential design exists to prevent. It is not a shortcut you
+are being denied; it is the thing that must not happen.
+
+So you never:
+
+- call `PUT /repos/{owner}/{repo}/actions/secrets/{name}`,
+- fetch `GET /repos/{owner}/{repo}/actions/secrets/public-key` in order to encrypt something,
+- ask a human to paste a token into chat so you can set it for them,
+- or accept one they volunteer. If a secret appears in the conversation anyway, do not use it, do
+  not repeat it, and tell them to rotate it.
+
+You hand them this instead:
+
+> **Settings → Secrets and variables → Actions → New repository secret** in `<owner>/<repo>`.
+> Name it exactly `<SECRET_NAME>`. Paste only the value — do not commit it anywhere, and do not
+> paste it into this chat.
+
+Then **wait for confirmation before dispatching anything that needs it.** A run that starts without
+its secret fails on the runner in a way that reads like a config problem, and you will spend the
+next twenty minutes debugging the wrong thing.
+
+What you *may* do: **list secret names.** `GET /repos/{owner}/{repo}/actions/secrets` returns names
+and timestamps and never a value. It is the honest way to verify a human's "I set it" without
+asking them twice, and it catches the common typo of a name that does not match the workflow's
+`${{ secrets.… }}` reference.
+
+Organization secrets, environment secrets, and Dependabot secrets are all covered by the same rule.
+
+---
+
+## Scopes, and what a 403 actually means
+
+**A 403 on an org-wide or account-wide listing endpoint is a normal permission boundary for an
+app-scoped or repo-scoped token. It is not a broken credential.**
+
+Misreading this cost a full debugging session once already, and nearly got a perfectly good
+credential replaced. A token scoped to one repository can fully manage that repository and still
+403 on any call that enumerates an organization or an account.
+
+The rule that follows: **prefer per-resource endpoints over listings.** Resolve `owner/repo` from
+the human, from the conversation, or from a file already in the repository — never by listing an
+org and searching it. If you have no identifier, ask. One question beats one wrong diagnosis.
+
+Roughly what each capability needs, so you can say something useful when a 403 does appear:
+
+| To do this | The token needs |
+|---|---|
+| Read a repository, its contents, its branches | read access to that repository |
+| Write files, create commits, update a ref | **write** access to repository contents |
+| Write anything under `.github/workflows/` | contents write **plus** workflow permission — a token without it is refused specifically on workflow paths and nowhere else, which is confusing if you do not know to look for it |
+| Dispatch a workflow, read runs and jobs | Actions permission (read for following, write for dispatching) |
+| Read secret **names** | Actions/secrets read |
+
+The workflow-permission row is the one that surprises people: a write that succeeds for every other
+path and fails only for `.github/workflows/…` is a scope problem, not a path problem.
+
+---
+
+## Reading `authDiagnostic`
+
+A 401 or 403 response from `custom_credential_make_request` carries an `authDiagnostic` object
+alongside GitHub's untouched `bodyText`. **Read it before reporting a bare failure.**
+
+- On a **401** where the scheme sent was `Bearer` and no username is stored, `hint` names the one
+  narrow guess the system is willing to make: this provider may need HTTP Basic with a saved
+  username. Treat it as a hypothesis. Ask the human for the username, save it with
+  `custom_credential_set_username`, retry **once**. Never invent a username, and never loop past
+  one retry.
+- When a username is already stored, there is no hint — the cause is something else and unguessable.
+- On a **403 there is no hint at all**, deliberately. 403 covers scopes, org policy, rate limits,
+  and missing headers; a Basic-auth guess there would be a false lead rather than a hedge. Report
+  the failure and GitHub's own message plainly.
+
+If you suspect the credential itself, `custom_credential_verify` checks one saved credential
+against its own API, live, and reports `valid` / `invalid` / `unreachable`. **`unreachable` does
+not mean the credential is bad** — it is a network failure. Do not tell a human to replace a token
+over a DNS error.
+
+---
+
+## Rate limits
+
+Every response carries `x-ratelimit-remaining` and `x-ratelimit-reset`. **A 403 with
+`x-ratelimit-remaining: 0` is a rate limit**, and saying "your token is broken" when a human is
+merely throttled is an avoidable, expensive mistake. Read the header before you diagnose.
+
+Polling an Actions run is the only thing here that makes a meaningful number of calls — which is
+the practical reason to leave a real gap between polls.
+
+---
+
+## The rule under all of the above
+
+**Never print, echo, or reconstruct a secret.** Not in a file you write, not in a commit message,
+not in a summary of what the human just did, not partially masked. Nothing in this plugin's
+procedures requires you to hold one, which is what makes that rule cheap to keep and inexcusable to
+break.