docs(actions): one reference per action, generated from action.yml; family guides; catalogue

.github/actions/claude-interactive/README.md

@@ -0,0 +1,67 @@
+# Claude Interactive
+
+`uses: megaeth-labs/.github/.github/actions/claude-interactive@main`
+
+<!-- generated: description -->
+Run the interactive @claude handler with centralized MegaETH permissions.
+<!-- /generated -->
+
+Family: [Claude CI](../CLAUDE-CI.md).
+
+## Inputs
+
+<!-- generated: inputs -->
+| Input | Required | Default | Description |
+|---|---|---|---|
+| `claude_code_oauth_token` | yes |  | OAuth token for Claude Code. |
+| `allowed_bots` | no | `mega-putin` | Bot accounts allowed to trigger Claude Code. |
+| `extra_allowed_tools` | no |  | Additional Claude tools to append to the canonical allowedTools list. |
+<!-- /generated -->
+
+## Outputs
+
+<!-- generated: outputs -->
+This action sets no outputs.
+<!-- /generated -->
+
+## What it runs
+
+<!-- generated: steps -->
+1. (unnamed run step)
+1. `anthropics/claude-code-action`
+<!-- /generated -->
+
+## Errors it reports
+
+<!-- generated: errors -->
+Its shell steps report no errors of their own; failures come from the actions and tools it calls.
+<!-- /generated -->
+
+## Example
+
+```yaml
+jobs:
+  interactive:
+    if: contains(github.event.comment.body, '@claude')   # plus the review/issue event variants
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      id-token: write
+      actions: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: megaeth-labs/.github/.github/actions/claude-interactive@main
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          extra_allowed_tools: "Bash(just:*),Bash(npm:*)"
+```
+
+## Notes
+
+- Handles `@claude` mentions in issue comments, PR review comments and
+  reviews with the organisation's permission set; there is no
+  `extra_prompt`, since `@claude` conversations are native.
+- `allowed_bots` names the bot accounts whose mentions may trigger it.

.github/actions/claude-issue-triage/README.md

@@ -0,0 +1,65 @@
+# Claude Issue Triage
+
+`uses: megaeth-labs/.github/.github/actions/claude-issue-triage@main`
+
+<!-- generated: description -->
+Run the centralized MegaETH Claude issue triage.
+<!-- /generated -->
+
+Family: [Claude CI](../CLAUDE-CI.md).
+
+## Inputs
+
+<!-- generated: inputs -->
+| Input | Required | Default | Description |
+|---|---|---|---|
+| `claude_code_oauth_token` | yes |  | OAuth token for Claude Code. |
+| `allowed_bots` | no | `mega-putin` | Bot accounts allowed to trigger Claude Code. |
+| `extra_allowed_tools` | no |  | Additional Claude tools to append to the canonical allowedTools list. |
+| `extra_prompt` | no |  | Additional prompt text appended after the canonical prompt. |
+<!-- /generated -->
+
+## Outputs
+
+<!-- generated: outputs -->
+This action sets no outputs.
+<!-- /generated -->
+
+## What it runs
+
+<!-- generated: steps -->
+1. (unnamed run step)
+1. `anthropics/claude-code-action`
+<!-- /generated -->
+
+## Errors it reports
+
+<!-- generated: errors -->
+Its shell steps report no errors of their own; failures come from the actions and tools it calls.
+<!-- /generated -->
+
+## Example
+
+```yaml
+on:
+  issues:
+    types: [opened]
+jobs:
+  triage:
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      issues: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: megaeth-labs/.github/.github/actions/claude-issue-triage@main
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+```
+
+## Notes
+
+- Triages newly opened issues with the centralised prompt plus the
+  repository's own convention files; `extra_prompt` appends per-repository
+  instructions.

.github/actions/claude-label-check/README.md

@@ -0,0 +1,69 @@
+# Claude Label Check
+
+`uses: megaeth-labs/.github/.github/actions/claude-label-check@main`
+
+<!-- generated: description -->
+Run the centralized MegaETH Claude pull request label check.
+<!-- /generated -->
+
+Family: [Claude CI](../CLAUDE-CI.md).
+
+## Inputs
+
+<!-- generated: inputs -->
+| Input | Required | Default | Description |
+|---|---|---|---|
+| `claude_code_oauth_token` | yes |  | OAuth token for Claude Code. |
+| `allowed_bots` | no | `mega-putin` | Bot accounts allowed to trigger Claude Code. |
+| `extra_allowed_tools` | no |  | Additional Claude tools to append to the canonical allowedTools list. |
+| `self_authored_logins` | no | `mega-maxwell[bot]` | Comma-separated logins whose pull requests are skipped rather than label-checked: the CI app's own PRs (release candidates, settle PRs, dependency bumps). claude-code-action refuses bot-initiated events, so without this the check fails instead of saying it does not apply. |
+| `extra_prompt` | no |  | Additional prompt text appended after the canonical prompt. |
+<!-- /generated -->
+
+## Outputs
+
+<!-- generated: outputs -->
+This action sets no outputs.
+<!-- /generated -->
+
+## What it runs
+
+<!-- generated: steps -->
+1. (unnamed run step)
+1. (unnamed run step) *(only if `steps.gate.outputs.skip != 'true'`)*
+1. `anthropics/claude-code-action` *(only if `steps.gate.outputs.skip != 'true'`)*
+<!-- /generated -->
+
+## Errors it reports
+
+<!-- generated: errors -->
+Its shell steps report no errors of their own; failures come from the actions and tools it calls.
+<!-- /generated -->
+
+## Example
+
+```yaml
+jobs:
+  label-check:
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      pull-requests: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: megaeth-labs/.github/.github/actions/claude-label-check@main
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          extra_prompt: |
+            This repository's label conventions are in CONTRIBUTING.md.
+```
+
+## Notes
+
+- PRs opened by any login in `self_authored_logins` (the CI app by
+  default) are skipped rather than checked: the app's release and
+  dependency PRs carry the labels the settle/candidate actions were given.
+- The prompt reads the repository's own convention files first
+  (`REVIEW.md`, `CLAUDE.md`, `AGENTS.md`, …); `extra_prompt` is for small
+  deltas only.

.github/actions/claude-pr-review/README.md

@@ -0,0 +1,100 @@
+# Claude PR Review
+
+`uses: megaeth-labs/.github/.github/actions/claude-pr-review@main`
+
+<!-- generated: description -->
+Run the staged, incremental MegaETH Claude pull request review.
+<!-- /generated -->
+
+Family: [Claude CI](../CLAUDE-CI.md).
+
+## Inputs
+
+<!-- generated: inputs -->
+| Input | Required | Default | Description |
+|---|---|---|---|
+| `claude_code_oauth_token` | yes |  | OAuth token for Claude Code. |
+| `github_identity_token` | no |  | Optional GitHub token used for review publication and state updates. When supplied, it is also used to resolve addressed automated review threads. Empty uses the job token and skips thread resolution. |
+| `allowed_bots` | no | `mega-putin` | Bot accounts allowed to trigger Claude Code. |
+| `extra_allowed_tools` | no |  | Additional read-only tools to append to the canonical allowedTools list. |
+| `extra_prompt` | no |  | Additional analysis instructions appended after the canonical prompt. |
+| `model` | no | `claude-opus-4-7` | Model used for full, high-risk, and deep reviews. |
+| `incremental_model` | no |  | Model used for low-risk incremental reviews. Empty uses the Claude Code default (Sonnet class). |
+| `review_depth` | no | `standard` | `standard` runs one lead review. `deep` asks the lead to fan out review dimensions and adversarially verify them before returning structured data. |
+| `max_turns` | no |  | Optional override for the per-invocation turn budget (`--max-turns`). Empty (default) uses the built-in budget derived from model tier and review depth (fast 12, standard 44, deep 56). Set a positive integer to pin the ceiling for the main analysis pass; the retry pass keeps its 1.5x headroom relative to this value. |
+| `debug_logs` | no | `false` | Deprecated and ignored. The analysis session's full output — its tool calls, the files it opened, and the ones it never read — is now always printed, and the whole `.pr-review` state directory plus the session transcript are uploaded as a run artifact. Kept only so consumers that still pass it do not break. |
+| `state_artifact` | no | `true` | `true` uploads the `.pr-review` state directory — routing input, both diffs, the raw model output, the compiled payload, the pipeline trace, and the analysis session transcript — as a run artifact. This is the only copy that outlives the runner, so leave it on unless the repository forbids artifacts. |
+| `state_artifact_retention_days` | no | `14` | Retention in days for the review state artifact. |
+| `premortem` | no | `auto` | `auto` runs the internal pre-mortem only for full or high-risk reviews. `on` always runs it; `off` disables it. Pre-mortem provenance never appears in the published review. |
+<!-- /generated -->
+
+## Outputs
+
+<!-- generated: outputs -->
+| Output | Description |
+|---|---|
+| `mode` | Review mode (`full`, `incremental`, or `skip`). |
+| `reviewed_head` | Frozen PR head reviewed by this run. |
+| `verdict` | Compiled verdict (`clean`, `findings`, or `questions`). |
+| `published` | Whether output was published for the frozen head. |
+<!-- /generated -->
+
+## What it runs
+
+<!-- generated: steps -->
+1. Prepare immutable review context
+1. Compose bounded LLM analysis
+1. Analyze and verify findings — `anthropics/claude-code-action` *(only if `steps.prepare.outputs.mode != 'skip'`)*
+1. Retry missing structured review output — `anthropics/claude-code-action` *(only if `steps.prepare.outputs.mode != 'skip' && (steps.review.outcome == 'failure' || steps.review.outputs.structured_output == '')`)*
+1. Capture analysis session transcript *(only if `always()`)*
+1. Compile and validate review
+1. Publish atomically and persist state
+1. Report concise review outcome *(only if `always()`)*
+1. Upload review state for inspection — `actions/upload-artifact` *(only if `always() && inputs.state_artifact == 'true'`)*
+<!-- /generated -->
+
+## Errors it reports
+
+<!-- generated: errors -->
+- `max_turns must be a positive integer, got`
+<!-- /generated -->
+
+## Example
+
+```yaml
+jobs:
+  pr-review:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 25
+    concurrency:
+      group: claude-pr-review-${{ github.event.pull_request.number }}
+      cancel-in-progress: true
+    permissions:
+      contents: read
+      pull-requests: write
+      id-token: write
+      actions: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - uses: megaeth-labs/.github/.github/actions/claude-pr-review@main
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          github_identity_token: ${{ steps.app-token.outputs.token }}   # optional: one identity for reviews, comments, thread resolution
+          extra_allowed_tools: "Bash(cargo:*)"
+```
+
+## Notes
+
+- How a round runs, the manifest, the questions lifecycle, the comment-
+  triggered reconciliation and how to inspect a run: [CLAUDE-CI.md](../CLAUDE-CI.md).
+- PRs opened by the identity behind `github_identity_token` (release
+  candidates, settle PRs, dependency bumps) are skipped before any model
+  step.
+- A PR that edits the calling repository's own `claude.yml` skips the review
+  by design of `claude-code-action`; it works again once the change merges.
+- Turn budgets: 12 for a low-risk incremental round, 44 for a strong-tier
+  one, 56 for `deep`; `max_turns` overrides, and the retry gets half again
+  as many.

.github/actions/pr-lint/README.md

@@ -0,0 +1,79 @@
+# PR Lint
+
+`uses: megaeth-labs/.github/.github/actions/pr-lint@main`
+
+<!-- generated: description -->
+Lint a pull request. Currently validates that the PR title follows Conventional Commits, posting a sticky comment on failure and removing it once fixed; further PR-level lint steps can be added here over time. Run as a step inside a job the consumer names, so the resulting status-check context is that job name.
+<!-- /generated -->
+
+Standalone action; no family guide.
+
+## Inputs
+
+<!-- generated: inputs -->
+| Input | Required | Default | Description |
+|---|---|---|---|
+| `types` | no | `feat
+fix
+chore
+test
+bench
+perf
+refactor
+docs
+ci
+revert
+deps
+` | Newline-separated list of allowed Conventional Commit types. Defaults to the MegaETH org convention. |
+| `github_token` | no | `${{ github.token }}` | Token used by the semantic-PR check and the sticky comment. |
+<!-- /generated -->
+
+## Outputs
+
+<!-- generated: outputs -->
+This action sets no outputs.
+<!-- /generated -->
+
+## What it runs
+
+<!-- generated: steps -->
+1. Skip for merge queue *(only if `github.event_name == 'merge_group'`)*
+1. Check title — `amannn/action-semantic-pull-request` *(only if `github.event_name == 'pull_request'`)*
+1. Add PR Comment for Invalid Title — `marocchino/sticky-pull-request-comment` *(only if `github.event_name == 'pull_request' && steps.lint_pr_title.outcome == 'failure'`)*
+1. Remove Comment for Valid Title — `marocchino/sticky-pull-request-comment` *(only if `github.event_name == 'pull_request' && steps.lint_pr_title.outcome == 'success'`)*
+1. Fail if title invalid *(only if `github.event_name == 'pull_request' && steps.lint_pr_title.outcome == 'failure'`)*
+<!-- /generated -->
+
+## Errors it reports
+
+<!-- generated: errors -->
+Its shell steps report no errors of their own; failures come from the actions and tools it calls.
+<!-- /generated -->
+
+## Example
+
+```yaml
+name: PR Lint
+on:
+  pull_request:
+    types: [opened, reopened, edited, synchronize]
+  merge_group:
+jobs:
+  conventional-title:
+    name: Validate PR title is Conventional Commit
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - uses: megaeth-labs/.github/.github/actions/pr-lint@main
+```
+
+## Notes
+
+- Run it as a step inside a job the consumer names: the status-check
+  context is the job name, so a branch ruleset that requires an exact check
+  name is satisfied by naming the job accordingly.
+- On a bad title it posts a sticky comment and fails; once the title is
+  fixed the comment is removed. Merge-queue events are skipped.
+- `types` overrides the allowed Conventional Commit types; the default is
+  the organisation's convention.