iam/v2-onboarding-sheep-dip-2026-05-02: agent auto-sync

.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`.

.gitignore

@@ -146,3 +146,67 @@ vite.config.ts.timestamp-*
 
 # AI memory (private — do not expose in public repos)
 .memory/
+
+# ───── IAM-managed sensitivity-tier baseline (auto-appended by onboard-agent.sh) ─────
+# Sensitivity tier: open-public
+# Used by: repos that are public OR will be public OR are read by external integrators
+# (e.g. kit, soon docs).
+# Rule: NEVER let anything sensitive land in these repos.
+# Owner: iam-agent (validated on every onboard-agent.sh run for open-public tier).
+
+# --- secrets / credentials (never in any repo, especially open-public) ---
+.env
+.env.*
+*.pem
+*.key
+*.p12
+*.pfx
+secrets/
+credentials.json
+gcp-key.json
+service-account*.json
+*.cert
+*.crt
+
+# --- internal dispatch artefacts (never publish to integrators) ---
+intake/responses/*.md
+intake/responses/*.err
+intake/processed/
+
+# --- internal correspondence / non-public memory ---
+MEMORY.local.md
+*.local.md
+.claude/memory/
+
+# --- build artefacts ---
+node_modules/
+dist/
+build/
+.turbo/
+.next/
+.cache/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# --- editor / OS ---
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*~
+
+# --- logs (may include sensitive request bodies) ---
+*.log
+logs/
+
+# --- test artefacts that may contain sample customer data ---
+test-fixtures/private/
+test-data/customer-*/
+
+# --- internal-only docs (never published) ---
+docs/internal/
+INTERNAL-*.md

ARCHITECTURE.md

@@ -0,0 +1,40 @@
+# kit — Architecture
+
+**Agent:** `kit-agent` · **Repo:** `kit` · **Domain:** `customer-external`
+
+> **TODO (kit-agent):** This file is a stub. Fill it before promoting
+> from `dormant` to `active`. The fleet audit checks for stub-level
+> content and flags it as a G2.3 gap.
+
+## What this system does
+
+> One paragraph, ELI10. What problem does this agent solve? Who is it for?
+
+## How it fits into Toreva
+
+> Diagram or bullet list. Upstream inputs (other agents this consumes from).
+> Downstream outputs (other agents this produces for). Bus topics published.
+> Bus topics subscribed.
+
+## Internal shape
+
+> Module / package / service breakdown. Where does state live? What's
+> permanent (in DB / GCS / GitHub)? What's ephemeral (in memory / tmp)?
+
+## Invariants
+
+> Things that MUST be true. E.g. "We never sign on behalf of a user."
+> "Every action publishes a receipt envelope." "Air-gap = zero, ever."
+
+## Failure modes
+
+> Known failure scenarios + how the system degrades. Fail-open vs fail-closed.
+
+## External dependencies
+
+> Third-party services, GCP services, on-chain programs.
+
+## Decisions log
+
+See [`docs/decisions/`](./docs/decisions/) for material architectural
+decisions (DEC- or ADR- documents).

BACKUP.md

@@ -0,0 +1,52 @@
+# kit — Backup, restore, persistence
+
+**Agent:** `kit-agent` · **Repo:** `kit` · **Domain:** `customer-external`
+
+What's permanent for this agent, where it lives, and how it survives
+catastrophic loss of the operator's laptop, local filesystem, or GitHub.
+
+## Source-of-truth map
+
+| Artefact | Permanent home | Ephemeral copy | Recoverable from |
+|---|---|---|---|
+| Code | GitHub `<github_org>/<home_repo>` | local `~/toreva_vs/<home_repo>` | GitHub remote |
+| `MEMORY.md` | GitHub | local | GitHub + memory-archive sweep |
+| `intake/processed/` (audit trail) | GitHub | local | GitHub remote |
+| `intake/responses/` (working drafts) | local only (gitignored on `open-public`) | local | NOT recoverable — by design |
+| Bus envelopes | `toreva-prod.coordinator_audit_prod.bus_events` (BigQuery) | none | BQ time-travel + GCS export |
+| Runtime SA credentials | GCP Secret Manager | runtime SA key cache | IAC dispatch to re-issue |
+| Per-agent GH identity | GitHub Org settings + GCP Secret Manager | runtime cache | IAC + IAM joint dispatch |
+
+## Recovery scenarios
+
+### Scenario A — operator laptop dies
+
+1. Provision new device.
+2. Re-clone `~/toreva_vs/<home_repo>` from GitHub.
+3. `MEMORY.md` survives (GitHub-resident).
+4. `intake/responses/` (work-in-progress drafts) is **not recoverable** for
+   `open-public` tier (gitignored to prevent leakage); `normal`/`hardened`
+   tier may be recoverable via GitHub if committed.
+5. Re-launch supervisor: `coordinator/scripts/supervisor.sh restart kit-agent`.
+
+### Scenario B — local filesystem corruption
+
+Same as Scenario A.
+
+### Scenario C — GitHub repo deleted / corrupted / org-level outage
+
+1. IAC dispatches a restore from the most recent GitHub-org-level backup
+   (target: GCS bucket `gs://toreva-prod-iam-backups/<github_org>/<home_repo>/`).
+2. Frequency: nightly snapshot via IAC's GitHub-backup workflow. **Not yet
+   provisioned for every agent — see G2.13.**
+3. Re-push to a fresh GitHub repo if the original cannot be restored.
+
+### Scenario D — Bus-history dataset corruption
+
+Coordinator-owned. Out of this agent's scope. See coordinator's runbook.
+
+## What is intentionally NOT permanent
+
+- `intake/responses/` work-in-progress drafts for `open-public` tier
+- Local `node_modules/`, `__pycache__/`, build outputs
+- Anything in `*.local.md` files