feat(dec-001): C7 — kit install package + toreva CLI + examples

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,85 @@
+name: Bug report
+description: Something in toreva/kit (SDK, MCP server tools, type schemas) is broken or behaves unexpectedly.
+title: "[bug] "
+labels: ["bug", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report. First-response SLA is under 4 hours during AEST business hours, under 24 hours otherwise.
+        See [`cdx/docs/triage-protocol.md`](https://github.com/toreva/cdx/blob/main/docs/triage-protocol.md).
+
+        If this is a **production-down** or **security** issue, also email `dev@toreva.io` with subject prefix `URGENT — production`.
+
+        If your question is "how do I…?" rather than "this is broken", post in [Discussions](https://github.com/toreva/kit/discussions) instead — gets faster, less formal answers.
+  - type: input
+    id: kit-version
+    attributes:
+      label: kit / package version
+      description: e.g. `@toreva/mcp 0.1.2`. Run `npm ls @toreva/mcp` or check your `package.json`.
+      placeholder: "@toreva/mcp 0.1.2"
+    validations:
+      required: true
+  - type: input
+    id: mcp-client
+    attributes:
+      label: MCP client (if relevant)
+      description: e.g. Claude desktop 0.7.x, Cursor 0.42.x, custom client. Leave blank if SDK-only bug.
+      placeholder: "Claude desktop 0.7.4"
+  - type: input
+    id: os
+    attributes:
+      label: OS + version
+      placeholder: "macOS 14.5"
+    validations:
+      required: true
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: One paragraph. What did you do, what did the system do.
+      placeholder: |
+        I called `place_order(wallet_id="...", asset="SOL", side="buy", amount=10)` from Claude desktop and got a 5xx with body `{"error": "..."}`.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+      placeholder: |
+        Per DEC-001 §MCP, `place_order` should return a receipt envelope with a real Solana tx signature.
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: Code, commands, or step-by-step. Smaller is better.
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant logs / error output
+      description: Redact any OAuth tokens or wallet addresses you don't want public. (We can never recover what you've already posted publicly.)
+      render: shell
+  - type: dropdown
+    id: severity
+    attributes:
+      label: Severity (your view)
+      options:
+        - "P0 — production down / financial loss imminent"
+        - "P1 — blocking my development, no workaround"
+        - "P2 — blocking my development, workaround exists"
+        - "P3 — annoying, not blocking"
+      default: 2
+    validations:
+      required: true
+  - type: checkboxes
+    id: regulated-claim-check
+    attributes:
+      label: Regulated-claim check
+      description: Tick if your bug touches Earn / Stake / Balance / yield / custody / "is this safe?" — we'll route via `compliance-agent` first.
+      options:
+        - label: This bug touches a regulated-financial-product surface (Earn, Stake, Balance, yield, return, custody, safety-of-funds claim).

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: General Q&A and how-to questions
+    url: https://github.com/toreva/kit/discussions
+    about: For "how do I…?" questions, design discussion, and showing off what you've built. Faster turn-around than Issues.
+  - name: Compliance-sensitive or private questions
+    url: mailto:dev@toreva.io
+    about: For anything you'd rather not post publicly (employer policy, regulated-product questions, security reports).
+  - name: Triage protocol & SLAs
+    url: https://github.com/toreva/cdx/blob/main/docs/triage-protocol.md
+    about: How we route issues and what response time to expect.

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,59 @@
+name: Feature request
+description: A primitive, tool, type schema, or capability you'd want kit / MCP to expose.
+title: "[feature] "
+labels: ["enhancement", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the suggestion. First-response SLA is under 4 hours during AEST business hours, under 24 hours otherwise.
+
+        If you're not sure whether what you want already exists, post in [Discussions](https://github.com/toreva/kit/discussions) first — saves us both a round trip.
+
+        Doctrine reference for what's locked vs open: [`po/docs/decisions/DEC-001-wallet-mode-architecture.md`](https://github.com/toreva/po/blob/main/docs/decisions/DEC-001-wallet-mode-architecture.md). The MCP tool surface in §"Connect integration mechanic — MCP" is the v0.2 lock; we're collecting feedback for v0.3.
+  - type: textarea
+    id: workflow
+    attributes:
+      label: What real workflow are you trying to build?
+      description: Spec-language preferred. "I want my agent to X, then Y, then Z." Concrete beats abstract.
+    validations:
+      required: true
+  - type: textarea
+    id: blocker
+    attributes:
+      label: What's blocking you today
+      description: What can't you do with the current kit / MCP surface? Be specific — tool name, missing parameter, missing return field, etc.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed shape (optional)
+      description: If you have a tool signature / type / API in mind, sketch it. We may converge on something different but your starting point helps.
+      render: typescript
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives you've tried
+      description: Workarounds in your own code, in another tool, in a competitor. Tells us how urgent the gap is.
+  - type: dropdown
+    id: scope-guess
+    attributes:
+      label: Where do you think this belongs (your guess)
+      description: We'll route correctly even if you guess wrong; this just helps speed up routing.
+      options:
+        - "kit / MCP tool surface"
+        - "kit / SDK type schemas"
+        - "gateway / MCP server runtime"
+        - "investment-product / strategy semantics"
+        - "pricing / rate card"
+        - "I genuinely don't know"
+      default: 5
+    validations:
+      required: true
+  - type: checkboxes
+    id: regulated-claim-check
+    attributes:
+      label: Regulated-claim check
+      options:
+        - label: This feature touches a regulated-financial-product surface (Earn, Stake, Balance, yield, return, custody). I understand the response will route via `compliance-agent` first.

.github/ISSUE_TEMPLATE/integration-help.yml

@@ -0,0 +1,68 @@
+name: Integration help
+description: You're trying to wire Toreva into your client / framework / workflow and stuck.
+title: "[help] "
+labels: ["question", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Welcome. If your question is "how do I install / authenticate / make my first tool call work", you're in the right place.
+
+        For lighter-weight Q&A, [Discussions](https://github.com/toreva/kit/discussions) gets faster turn-around. Issues are best when you've already tried and hit a wall worth tracking.
+
+        Canonical install reference: [`kit/README.md`](https://github.com/toreva/kit/blob/main/README.md) and the per-skill docs under [`kit/skills/`](https://github.com/toreva/kit/tree/main/skills).
+  - type: input
+    id: client
+    attributes:
+      label: What client / framework / tool are you trying to integrate from?
+      placeholder: "Claude desktop / Cursor / LangChain / custom Python / something else"
+    validations:
+      required: true
+  - type: input
+    id: kit-version
+    attributes:
+      label: kit / package version
+      placeholder: "@toreva/mcp 0.1.2"
+  - type: textarea
+    id: goal
+    attributes:
+      label: What's your goal — in one sentence
+      description: "I want my agent to X" — the workflow you want to enable, not the technical step.
+      placeholder: "I want my Cursor session to be able to check my Toreva balance and place a small SOL trade when I tell it to."
+    validations:
+      required: true
+  - type: textarea
+    id: tried
+    attributes:
+      label: What you've tried so far
+      description: Doc links you've followed, commands you've run, error messages you've hit. Copy-paste exact strings — paraphrase loses signal.
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: stuck-on
+    attributes:
+      label: Where you're stuck
+      description: One paragraph. The current symptom and the gap between current state and goal.
+    validations:
+      required: true
+  - type: dropdown
+    id: stage
+    attributes:
+      label: At what stage of integration are you stuck?
+      options:
+        - "Install — can't get the MCP server / SDK installed"
+        - "Auth — install works but token / OAuth / delegation isn't accepted"
+        - "First tool call — auth works but tool calls fail"
+        - "Specific tool semantics — most tools work but one is behaving wrong"
+        - "Receipts / explanation — tool calls work but I can't make sense of the receipts"
+        - "Beyond setup — performance / scale / reliability"
+      default: 0
+    validations:
+      required: true
+  - type: checkboxes
+    id: regulated-claim-check
+    attributes:
+      label: Regulated-claim check
+      options:
+        - label: My question touches a regulated-financial-product surface (Earn, Stake, Balance, yield, return, custody). I understand parts of my answer may route via `compliance-agent`.

README.md

@@ -8,37 +8,70 @@ Your agent decides. Toreva executes. Every action receipted.
 
 ## Install
 
+The fastest path — wires Toreva into your MCP-aware client (Claude
+Desktop, OpenClaw, Cursor) and authenticates you in two commands:
+
 ```bash
-npm install @toreva/sdk
-npm install -g @toreva/cli
+npx toreva init --client=claude-desktop   # or openclaw | cursor
+npx toreva login
 ```
 
-### MCP server (stdio)
+`toreva init` writes the Toreva MCP server stanza into your client's
+config file. `toreva login` runs the gateway's device-code flow and
+stores the resulting token at `~/.config/toreva/config.json` (chmod
+600).
+
+Restart your MCP client and verify:
 
 ```bash
-RELAY_AUTH_TOKEN=your_token npx @toreva/mcp
+npx toreva doctor
 ```
 
-### MCP server (remote)
+You should see three `[ OK ]` lines: `config_present`, `auth_token`,
+`mcp_call`.
 
-No install needed — connect directly:
+Per-client snippets live in [`examples/`](./examples/) — one folder per
+supported client (`claude-desktop`, `openclaw`, `cursor`).
 
+### Direct package installs (advanced)
+
+```bash
+npm install @toreva/sdk        # TypeScript client library
+npm install -g @toreva/cli     # global `toreva` binary
 ```
-https://gateway.toreva.com/mcp
+
+### MCP server (stdio, run-it-yourself)
+
+```bash
+TOREVA_AUTH_TOKEN=your_token npx @toreva/mcp
 ```
 
-## Authentication
+### MCP server (remote, no install)
 
-All commands — including read-only queries — require a `RELAY_AUTH_TOKEN`.
+```
+https://mcp.toreva.com
+```
+
+## Authentication
 
-Set it as an environment variable:
+`toreva login` is the standard path. For CI / power users, set
+`TOREVA_AUTH_TOKEN` directly to skip the device-code flow:
 
 ```bash
-export RELAY_AUTH_TOKEN=your_token
+export TOREVA_AUTH_TOKEN=your_token
+npx toreva login   # writes the token to ~/.config/toreva/config.json
 ```
 
 Request a token at [toreva.com/docs](https://toreva.com/docs).
 
+### Environment variables
+
+| Var | Default | Purpose |
+| --- | --- | --- |
+| `TOREVA_MCP_URL` | `https://mcp.toreva.com` | Gateway URL |
+| `TOREVA_AUTH_TOKEN` | — | Skip device-code flow, persist this token |
+| `TOREVA_CONFIG_DIR` | `~/.config/toreva` | Override on-disk config dir |
+
 ## Perps tools
 
 | Tool | Fee | What it does |

bin/toreva

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// Repo-root shim for `npx toreva` against this monorepo.
+// Published `npx @toreva/cli` runs packages/cli/dist/index.js directly via its own bin.
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const cliDist = join(here, '..', 'packages', 'cli', 'dist', 'index.js');
+
+if (!existsSync(cliDist)) {
+  console.error(
+    `[toreva] Built CLI not found at ${cliDist}.\n` +
+      `Run \`pnpm -C packages/cli build\` first, or install the published \`@toreva/cli\`.`
+  );
+  process.exit(1);
+}
+
+const res = spawnSync(process.execPath, [cliDist, ...process.argv.slice(2)], { stdio: 'inherit' });
+process.exit(res.status ?? 1);

examples/claude-desktop/README.md

@@ -0,0 +1,37 @@
+# Claude Desktop — Toreva MCP
+
+Quick start (one command):
+
+```bash
+npx toreva init --client=claude-desktop
+npx toreva login
+```
+
+Then quit + relaunch Claude Desktop.
+
+## Manual install
+
+If you'd rather edit the config yourself, copy the snippet from
+[`claude_desktop_config.json`](./claude_desktop_config.json) into your
+Claude Desktop config file:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
+If the file already has an `mcpServers` block, merge `toreva` into it
+rather than replacing the whole block.
+
+## First-run check
+
+```bash
+npx toreva doctor
+```
+
+Should report `[ OK ]` for `config_present`, `auth_token`, and
+`mcp_call`.
+
+## Override the gateway URL
+
+Set `TOREVA_MCP_URL` before `toreva init` (or edit the `env` block in the
+config snippet) to point at a non-prod gateway.

examples/claude-desktop/claude_desktop_config.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "toreva": {
+      "command": "npx",
+      "args": ["-y", "@toreva/mcp"],
+      "env": {
+        "TOREVA_MCP_URL": "https://mcp.toreva.com"
+      }
+    }
+  }
+}