docs: prepare open source staging onboarding

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+# SynapseNetwork does not currently publish a public sponsorship endpoint for this SDK.
+# Keep this file so open-source tooling can discover the funding policy explicitly.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,40 @@
+---
+name: Bug report
+about: Report an SDK bug or staging integration issue
+title: "[Bug]: "
+labels: bug
+---
+
+## Summary
+
+## SDK Surface
+
+- [ ] Python
+- [ ] TypeScript
+- [ ] Docs / examples
+
+## Invocation Mode
+
+- [ ] Fixed-price API invoke
+- [ ] Token-metered LLM invoke
+- [ ] Owner/provider control API
+
+## Environment
+
+- Gateway: staging (`https://api-staging.synapse-network.ai`)
+- Chain: Arbitrum Sepolia
+- Asset: MockUSDC
+
+## Reproduction
+
+```text
+Steps, redacted code, request id, and idempotency key.
+```
+
+## Expected Behavior
+
+## Actual Behavior
+
+## Notes
+
+Do not include private keys, seed phrases, real credentials, or production tokens.

.github/ISSUE_TEMPLATE/docs_request.md

@@ -0,0 +1,16 @@
+---
+name: Docs request
+about: Request a README, docs, or AI-agent instruction improvement
+title: "[Docs]: "
+labels: documentation
+---
+
+## What is unclear?
+
+## Which page or file?
+
+## Expected developer outcome
+
+## Notes
+
+Public docs should remain staging-first until production docs are officially live.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,33 @@
+---
+name: Feature request
+about: Propose an SDK capability, docs improvement, or staging integration helper
+title: "[Feature]: "
+labels: enhancement
+---
+
+## Summary
+
+## SDK Surface
+
+- [ ] Python
+- [ ] TypeScript
+- [ ] Docs / examples
+- [ ] Agent / MCP usage
+
+## Use Case
+
+Describe the staging integration or developer workflow this would improve.
+
+## Proposed Behavior
+
+## Alternatives Considered
+
+## Environment
+
+- Gateway: staging (`https://api-staging.synapse-network.ai`)
+- Chain: Arbitrum Sepolia
+- Asset: MockUSDC for integration testing
+
+## Notes
+
+Do not include private keys, seed phrases, real credentials, or production tokens.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,16 @@
+## Summary
+
+-
+
+## Validation
+
+- [ ] `bash scripts/ci/pr_checks.sh`
+
+## Public SDK Contract Checklist
+
+- [ ] Public examples use `SYNAPSE_AGENT_KEY`.
+- [ ] Public docs/examples point to staging, Arbitrum Sepolia, and MockUSDC where environment details are needed.
+- [ ] Fixed-price examples pass discovered prices as strings.
+- [ ] Token-metered LLM examples use `invoke_llm()` / `invokeLlm()` without `cost_usdc` / `costUsdc`.
+- [ ] Public `SynapseAuth` / `SynapseProvider` returns use named models/interfaces, not raw maps.
+- [ ] No private keys, seed phrases, credentials, or production tokens are committed.

.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  quality-gates:
+    name: SDK PR quality gates
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Run PR quality gates
+        run: bash scripts/ci/pr_checks.sh

CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable public SDK changes should be recorded here.
+
+## 0.1.0 - Public Preview
+
+- Published staging-first Python and TypeScript SDK guidance.
+- Standardized agent runtime credentials on `SYNAPSE_AGENT_KEY`.
+- Documented two invocation modes: fixed-price API invoke and token-metered LLM invoke.
+- Added typed owner/provider SDK return objects.
+- Removed local gateway environment from public SDK presets and examples.

CODE_OF_CONDUCT.md

@@ -0,0 +1,25 @@
+# Code of Conduct
+
+## Our Pledge
+
+We want the SynapseNetwork SDK community to be useful, respectful, and safe for developers building agent payment integrations. Be direct, kind, and professional.
+
+## Expected Behavior
+
+- Use welcoming and inclusive language.
+- Respect different experience levels and time zones.
+- Give constructive feedback focused on the work.
+- Handle security, credentials, and financial-flow topics with care.
+
+## Unacceptable Behavior
+
+- Harassment, insults, threats, or discriminatory language.
+- Publishing another person's private information.
+- Sharing credentials, private keys, seed phrases, or other sensitive material.
+- Deliberately misleading users about staging, testnet assets, or production readiness.
+
+## Enforcement
+
+Maintainers may edit, hide, or remove comments, issues, pull requests, or contributions that violate this code of conduct. Serious or repeated violations may result in a ban from project spaces.
+
+Report concerns through the support or security channels listed in `SUPPORT.md` and `SECURITY.md`.

CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+Thanks for improving the SynapseNetwork SDK. This repository is public-facing, so every change should keep the developer and AI-agent onboarding path clear, staging-first, and safe.
+
+## Before You Start
+
+1. Read `llms.txt`.
+2. Use `SYNAPSE_AGENT_KEY` for agent runtime examples.
+3. Treat `staging` as the only public preview environment.
+4. Use Arbitrum Sepolia and MockUSDC in staging docs; do not document local gateway setup as the public integration path.
+5. Never commit private keys, seed phrases, real credentials, or production tokens.
+
+## Development
+
+Python:
+
+```bash
+cd python
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+```
+
+TypeScript:
+
+```bash
+cd typescript
+npm install
+```
+
+## Quality Gates
+
+Run the full PR gate before opening or updating a pull request:
+
+```bash
+bash scripts/ci/pr_checks.sh
+```
+
+Focused checks:
+
+```bash
+bash scripts/ci/repo_hygiene_checks.sh
+bash scripts/ci/python_checks.sh
+bash scripts/ci/typescript_checks.sh
+```
+
+## SDK Contract Rules
+
+- Public `SynapseAuth` and `SynapseProvider` methods must return named SDK models/interfaces, not raw maps.
+- Fixed-price API examples must pass discovered prices as strings, for example `cost_usdc="0.05"` or `costUsdc: "0.05"`.
+- Token-metered LLM examples must use `invoke_llm()` / `invokeLlm()` and must not pass `cost_usdc` / `costUsdc`.
+- New public behavior needs tests and docs in the same change.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Synapse Network Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,16 @@
+## Summary
+
+-
+
+## Validation
+
+- [ ] `bash scripts/ci/pr_checks.sh`
+
+## Public SDK Contract Checklist
+
+- [ ] Public examples use `SYNAPSE_AGENT_KEY`.
+- [ ] Public docs/examples point to staging, Arbitrum Sepolia, and MockUSDC where environment details are needed.
+- [ ] Fixed-price examples pass discovered prices as strings.
+- [ ] Token-metered LLM examples use `invoke_llm()` / `invokeLlm()` without `cost_usdc` / `costUsdc`.
+- [ ] Public `SynapseAuth` / `SynapseProvider` returns use named models/interfaces, not raw maps.
+- [ ] No private keys, seed phrases, credentials, or production tokens are committed.

README.md

@@ -26,6 +26,26 @@ SynapseNetwork lets an agent discover services, invoke them through a gateway, a
 > Public Preview default: SDK examples use `staging`, backed by `https://api-staging.synapse-network.ai`.
 > After production launch, replace the public examples and tests with the `prod` environment.
 
+## Staging Public Preview
+
+Today, public developer onboarding runs on staging:
+
+- Gateway: `https://api-staging.synapse-network.ai`
+- App docs: [staging.synapse-network.ai/docs/sdk](https://staging.synapse-network.ai/docs/sdk)
+- Chain: Arbitrum Sepolia testnet
+- Asset: MockUSDC for integration testing, not production USDC
+
+Recommended path:
+
+1. Connect a wallet in the staging Gateway Dashboard.
+2. Get or issue an Agent Key and export it as `SYNAPSE_AGENT_KEY`.
+3. Set `SYNAPSE_ENV=staging`.
+4. Use free services first, or fund staging balance with MockUSDC before paid test calls.
+5. Run one fixed-price API invoke and one token-metered LLM invoke.
+6. Read the invocation receipt and verify settlement metadata.
+
+Developers should pass staging before any future production migration. Production docs and examples stay reserved until production DNS, contracts, gateway health, and docs deployment are verified.
+
 ## Choose Your Integration Path
 
 | Goal | Use |
@@ -272,7 +292,7 @@ Credential handling and vulnerability reporting live in [SECURITY.md](./SECURITY
 The Python examples are staging-first and live under `python/examples`.
 
 ```bash
-cd /Users/cliff/workspace/agent/Synapse-Network-Sdk/python
+cd python
 ```
 
 Register a provider service on staging:

README.zh-CN.md

@@ -26,6 +26,26 @@ SynapseNetwork 让 Agent 可以发现服务、通过 gateway 调用服务，并
 > Public Preview 默认使用 `staging`，对应 `https://api-staging.synapse-network.ai`。
 > 生产环境上线后，再把公开示例和测试统一切换到 `prod`。
 
+## Staging Public Preview
+
+当前公开开发者接入统一走 staging：
+
+- Gateway：`https://api-staging.synapse-network.ai`
+- App docs：[staging.synapse-network.ai/docs/sdk](https://staging.synapse-network.ai/docs/sdk)
+- 链：Arbitrum Sepolia 测试网
+- 资产：MockUSDC，用于接入测试，不是生产 USDC
+
+推荐路径：
+
+1. 在 staging Gateway Dashboard 连接钱包。
+2. 获取或签发 Agent Key，并设置为 `SYNAPSE_AGENT_KEY`。
+3. 设置 `SYNAPSE_ENV=staging`。
+4. 先调用免费服务；如需付费测试，先准备 MockUSDC 测试余额。
+5. 跑通一次 fixed-price API invoke 和一次 token-metered LLM invoke。
+6. 读取 invocation receipt，确认结算元数据。
+
+开发者应先在 staging 验证通过。Production docs 与示例会在生产 DNS、合约、gateway health 和 docs deployment 验证后再统一切换。
+
 ## 选择你的接入路径
 
 | 目标 | 使用 |

SUPPORT.md

@@ -0,0 +1,28 @@
+# Support
+
+## Public Preview Support
+
+The SDK is currently documented for staging public preview:
+
+- Gateway: `https://api-staging.synapse-network.ai`
+- App docs: `https://staging.synapse-network.ai/docs/sdk`
+- Chain: Arbitrum Sepolia
+- Asset: MockUSDC, not production USDC
+
+Developers should validate integrations on staging before any future production migration.
+
+## Before Opening an Issue
+
+Please include:
+
+- SDK language and version.
+- Whether you are using fixed-price `invoke()` / `invoke` or token-metered `invoke_llm()` / `invokeLlm()`.
+- Gateway environment, normally `staging`.
+- Request ID and idempotency key if an invocation failed.
+- Redacted error payloads and stack traces.
+
+Never paste private keys, seed phrases, real credentials, or production tokens.
+
+## Security Reports
+
+Use `SECURITY.md` for vulnerability reports or credential exposure concerns.

docs/README.md

@@ -0,0 +1,29 @@
+# SynapseNetwork SDK Documentation
+
+This directory is the public documentation source for the SynapseNetwork SDK repository.
+
+## Start Here
+
+1. [Getting Started](./guides/getting-started.md)
+2. [SDK Docs Hub](./sdk/README.md)
+3. [SDK/API Parity Matrix](./sdk/api-parity-matrix.md)
+4. [Quality Gates](./quality-gates.md)
+5. [Agent Map](./agent-map/README.md)
+
+## Public Preview Environment
+
+Public developer onboarding uses staging:
+
+- Gateway: `https://api-staging.synapse-network.ai`
+- Chain: Arbitrum Sepolia testnet
+- Asset: MockUSDC for integration testing, not production USDC
+
+Production docs and examples will be switched after production DNS, gateway health, contracts, and docs deployment are verified.
+
+## Contributor Notes
+
+Run the SDK PR gate before opening a pull request:
+
+```bash
+bash scripts/ci/pr_checks.sh
+```