@seeed-studio/meshtastic 0.1.1 → 0.2.1

package/.github/translate/glossary/ja.md

@@ -0,0 +1,23 @@
+channel plugin → チャンネルプラグイン
+channel → チャンネル (when referring to messaging channels)
+group channel → グループチャンネル
+group policy → グループポリシー
+DM → DM (keep English)
+access control → アクセス制御
+allowlist → 許可リスト
+mention gating → @mention ゲーティング
+pairing → ペアリング
+node → ノード
+gateway → ゲートウェイ
+mesh network → メッシュネットワーク
+transport → トランスポート
+repository → リポジトリ
+pull request → Pull Request (keep English)
+issue → issue (keep English)
+broker → broker (keep English, MQTT term)
+Serial → Serial (keep English in transport context)
+AI Agent → AI Agent (keep English)
+MeshClaw → MeshClaw (keep English)
+OpenClaw → OpenClaw (keep English)
+Meshtastic → Meshtastic (keep English)
+LoRa → LoRa (keep English)

package/.github/translate/glossary/pt.md

@@ -0,0 +1,23 @@
+channel plugin → plugin de canal
+channel → canal (when referring to messaging channels)
+group channel → canal de grupo
+group policy → política de grupo
+DM → mensagem direta
+access control → controle de acesso
+allowlist → lista de permissões
+mention gating → filtragem por @mention
+pairing → pareamento
+node → nó
+gateway → gateway
+mesh network → rede mesh
+transport → transporte
+repository → repositório
+pull request → Pull Request (keep English)
+issue → issue (keep English)
+broker → broker (keep English, MQTT term)
+Serial → Serial (keep English in transport context)
+AI Agent → AI Agent (keep English)
+MeshClaw → MeshClaw (keep English)
+OpenClaw → OpenClaw (keep English)
+Meshtastic → Meshtastic (keep English)
+LoRa → LoRa (keep English)

package/.github/translate/glossary/zh-CN.md

@@ -0,0 +1,23 @@
+channel plugin → 频道插件
+channel → 频道 (when referring to messaging channels)
+group channel → 群组频道
+group policy → 群组策略
+DM → 私信
+access control → 访问控制
+allowlist → 白名单
+mention gating → @mention 门控
+pairing → 配对
+node → 节点
+gateway → 网关
+mesh network → mesh 网络
+transport → 传输方式
+repository → 仓库
+pull request → Pull Request (keep English)
+issue → issue (keep English)
+broker → broker (keep English, MQTT term)
+Serial → Serial (keep English in transport context)
+AI Agent → AI Agent (keep English)
+MeshClaw → MeshClaw (keep English)
+OpenClaw → OpenClaw (keep English)
+Meshtastic → Meshtastic (keep English)
+LoRa → LoRa (keep English)

package/.github/translate/languages.json

@@ -0,0 +1,37 @@
+[
+  {
+    "code": "zh-CN",
+    "name": "Simplified Chinese",
+    "label": "中文",
+    "target": "README.zh-CN.md",
+    "toc_pattern": "目录|Table of Contents"
+  },
+  {
+    "code": "ja",
+    "name": "Japanese",
+    "label": "日本語",
+    "target": "README.ja.md",
+    "toc_pattern": "目次|Table of Contents"
+  },
+  {
+    "code": "fr",
+    "name": "French",
+    "label": "Français",
+    "target": "README.fr.md",
+    "toc_pattern": "Sommaire|Table des matières|Table of Contents"
+  },
+  {
+    "code": "pt",
+    "name": "Portuguese",
+    "label": "Português",
+    "target": "README.pt.md",
+    "toc_pattern": "Sumário|Índice|Table of Contents"
+  },
+  {
+    "code": "es",
+    "name": "Spanish",
+    "label": "Español",
+    "target": "README.es.md",
+    "toc_pattern": "Índice|Tabla de contenidos|Table of Contents"
+  }
+]

package/.github/translate/prompts/es.md

@@ -0,0 +1,16 @@
+You are a native Spanish technical writer translating an open-source README. Write like a Spanish-speaking developer writing docs for other Spanish-speaking developers — clear, direct, and natural. DO NOT produce literal/mechanical translation. Rephrase for natural Spanish reading flow.
+
+Examples of BAD vs GOOD translations:
+  BAD:  Este repositorio es un plugin de canal de OpenClaw, no es una aplicación independiente.
+  GOOD: Este es un plugin de canal para OpenClaw, no una aplicación independiente.
+  BAD:  Necesitas un gateway de OpenClaw en ejecución (Node.js 22+) para usarlo.
+  GOOD: Se requiere un gateway OpenClaw (Node.js 22+) en ejecución para usar este plugin.
+  BAD:  Al enviar un problema, incluya el modo de transporte, la configuración editada.
+  GOOD: Al crear una issue, incluye el tipo de transporte y la configuración (sin secretos).
+  BAD:  Las solicitudes de extracción son bienvenidas
+  GOOD: Los Pull Requests son bienvenidos
+
+Rules:
+- Use tú (informal) — natural for developer-to-developer communication
+- Keep technical terms in English when commonly used in Spanish dev community (e.g. plugin, broker, gateway)
+- Use neutral Spanish (avoid region-specific expressions) for broader reach

package/.github/translate/prompts/fr.md

@@ -0,0 +1,16 @@
+You are a native French technical writer translating an open-source README. Write like a French developer writing docs for other French developers — clear, precise, and natural. DO NOT produce literal/mechanical translation. Rephrase for natural French reading flow.
+
+Examples of BAD vs GOOD translations:
+  BAD:  Ce dépôt est un plugin de canal OpenClaw, ce n'est pas une application autonome.
+  GOOD: Ceci est un plugin de canal pour OpenClaw, pas une application autonome.
+  BAD:  Vous avez besoin d'une passerelle OpenClaw en cours d'exécution (Node.js 22+) pour l'utiliser.
+  GOOD: Une passerelle OpenClaw (Node.js 22+) est requise pour utiliser ce plugin.
+  BAD:  Lors de la soumission d'un problème, incluez le mode de transport, la configuration éditée.
+  GOOD: Lors de la création d'une issue, joignez le type de transport et la configuration (sans les secrets).
+  BAD:  Les demandes de tirage sont les bienvenues
+  GOOD: Les Pull Requests sont les bienvenues
+
+Rules:
+- Use vous (formal) for technical documentation
+- Keep technical terms in English when commonly used in French dev community (e.g. plugin, broker, gateway)
+- Use inclusive writing sparingly — prioritize clarity

package/.github/translate/prompts/ja.md

@@ -0,0 +1,17 @@
+You are a native Japanese technical writer translating an open-source README. Write like a Japanese engineer writing docs for other Japanese developers — clear, professional, and natural. Use です/ます style consistently.
+DO NOT produce literal/mechanical translation. Rephrase for natural Japanese reading flow.
+
+Examples of BAD vs GOOD translations:
+  BAD:  このリポジトリはOpenClawチャネルプラグインであり、スタンドアロンアプリケーションではありません。
+  GOOD: OpenClaw のチャンネルプラグインです。スタンドアロンアプリではありません。
+  BAD:  それを使用するためには、実行中のOpenClawゲートウェイ（Node.js 22+）が必要です。
+  GOOD: 利用には OpenClaw ゲートウェイ（Node.js 22+）が必要です。
+  BAD:  問題を提出する際には、トランスポートモード、編集された設定を含めてください。
+  GOOD: issue を作成する際は、トランスポート種別・設定（秘密情報は除く）を添えてください。
+  BAD:  プルリクエストは歓迎されます
+  GOOD: Pull Request を歓迎します
+
+Rules:
+- Use です/ます form (polite, standard technical docs)
+- Keep Katakana for established loanwords (e.g. プラグイン, ノード)
+- Add half-width space between Japanese and alphanumeric characters

package/.github/translate/prompts/pt.md

@@ -0,0 +1,16 @@
+You are a native Portuguese technical writer translating an open-source README. Write like a Brazilian/Portuguese developer writing docs for other Portuguese-speaking developers — clear, direct, and natural. DO NOT produce literal/mechanical translation. Rephrase for natural Portuguese reading flow.
+
+Examples of BAD vs GOOD translations:
+  BAD:  Este repositório é um plugin de canal OpenClaw, não é um aplicativo autônomo.
+  GOOD: Este é um plugin de canal para o OpenClaw, não um aplicativo independente.
+  BAD:  Você precisa de um gateway OpenClaw em execução (Node.js 22+) para usá-lo.
+  GOOD: É necessário ter um gateway OpenClaw (Node.js 22+) em execução para usar este plugin.
+  BAD:  Ao enviar um problema, inclua o modo de transporte, a configuração editada.
+  GOOD: Ao criar uma issue, inclua o tipo de transporte e a configuração (sem segredos).
+  BAD:  Pedidos de pull são bem-vindos
+  GOOD: Pull Requests são bem-vindos
+
+Rules:
+- Use você (informal) — standard in Brazilian Portuguese tech docs
+- Keep technical terms in English when commonly used (e.g. plugin, broker, gateway)
+- Prefer Brazilian Portuguese conventions as they are more widely used in tech

package/.github/translate/prompts/zh-CN.md

@@ -0,0 +1,15 @@
+You are a native Simplified Chinese technical writer translating an open-source README. Write like a Chinese developer writing docs for other Chinese developers — concise, direct, natural. DO NOT produce literal/mechanical translation. Rephrase for natural Chinese reading flow.
+
+Examples of BAD vs GOOD translations:
+  BAD:  此存储库是一个 OpenClaw 通道插件，不是一个独立的应用程序。
+  GOOD: 这是 OpenClaw 的频道插件，不是独立应用。
+  BAD:  您需要一个正在运行的 OpenClaw 网关（Node.js 22+）才能使用它。
+  GOOD: 需要先安装并运行 OpenClaw 网关（Node.js 22+）。
+  BAD:  在提交问题时要包括传输模式、编辑后的配置。
+  GOOD: 提 issue 时请附上传输方式、配置（隐去密钥）。
+  BAD:  欢迎拉取请求
+  GOOD: 欢迎提交 Pull Request
+
+Rules:
+- Use 你 not 您
+- Omit unnecessary 的、了、一个、进行 — keep sentences tight

package/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    environment: NPM_KEY
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+
+      - run: npm install
+
+      - run: npm publish --provenance --access public

package/.github/workflows/readme-translate.yml

@@ -0,0 +1,166 @@
+name: Translate README
+
+on:
+  issue_comment:
+    types: [created]
+  workflow_dispatch:
+
+concurrency:
+  group: translate-readme-${{ github.event.issue.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  pull-requests: write
+
+env:
+  LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
+  LLM_BASE_URL: ${{ vars.LLM_BASE_URL || 'https://api.apimart.ai/v1/chat/completions' }}
+  LLM_MODEL: ${{ vars.LLM_MODEL || 'gpt-5' }}
+  LLM_TIMEOUT: ${{ vars.LLM_TIMEOUT || '300' }}
+
+jobs:
+  # Job 1: PR 中通过 /translate 评论手动触发
+  translate-pr:
+    if: >-
+      github.event_name == 'issue_comment'
+      && github.event.issue.pull_request
+      && contains(github.event.comment.body, '/translate')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Add reaction to comment
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COMMENT_ID: ${{ github.event.comment.id }}
+        run: |
+          gh api "repos/${{ github.repository }}/issues/comments/${COMMENT_ID}/reactions" \
+            -f content='eyes' --silent
+
+      - name: Get PR head ref
+        id: pr
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.issue.number }}
+        run: |
+          PR_DATA=$(gh api "repos/${{ github.repository }}/pulls/${PR_NUMBER}")
+          echo "ref=$(echo "$PR_DATA" | jq -r .head.ref)" >> "$GITHUB_OUTPUT"
+          echo "sha=$(echo "$PR_DATA" | jq -r .head.sha)" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout PR branch
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          ref: ${{ steps.pr.outputs.ref }}
+          fetch-depth: 0
+
+      - name: Check if README.md changed
+        id: check
+        run: |
+          if git diff --name-only origin/main...HEAD | grep -q '^README.md$'; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Skip if README unchanged
+        if: steps.check.outputs.changed != 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.issue.number }}
+        run: |
+          gh pr comment "${PR_NUMBER}" \
+            --repo "${{ github.repository }}" \
+            --body "No changes to README.md detected in this PR. Skipping translation."
+
+      - name: Set up Python
+        if: steps.check.outputs.changed == 'true'
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: "3.12"
+
+      - name: Translate to all languages
+        if: steps.check.outputs.changed == 'true'
+        run: python .github/scripts/translate_readme.py --all
+        continue-on-error: true
+
+      - name: Commit and push translated READMEs
+        if: steps.check.outputs.changed == 'true'
+        run: |
+          TARGETS=$(python3 -c "import json; print(' '.join(l['target'] for l in json.load(open('.github/translate/languages.json'))))")
+          git add README.md
+          for f in $TARGETS; do
+            [ -f "$f" ] && git add "$f"
+          done
+          if git diff --cached --quiet; then
+            echo "No translation changes detected."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git commit -m "docs: auto-translate README files from README.md"
+          # Retry push with rebase to handle concurrent commits
+          for i in 1 2 3; do
+            git push && exit 0
+            echo "Push failed (attempt $i/3), pulling with rebase..."
+            git pull --rebase
+          done
+          echo "Push failed after 3 attempts"
+          exit 1
+
+      - name: Report result
+        if: always() && steps.check.outputs.changed == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.issue.number }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          if [ "${{ job.status }}" = "success" ]; then
+            gh pr comment "${PR_NUMBER}" \
+              --repo "${{ github.repository }}" \
+              --body "Translation complete. Translated READMEs have been committed to this PR branch."
+          else
+            gh pr comment "${PR_NUMBER}" \
+              --repo "${{ github.repository }}" \
+              --body "Translation failed. Please check the [workflow logs](${RUN_URL})."
+          fi
+
+  # Job 2: workflow_dispatch 手动触发（在 main 上直接翻译）
+  translate-manual:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: "3.12"
+
+      - name: Translate to all languages
+        run: python .github/scripts/translate_readme.py --all
+        continue-on-error: true
+
+      - name: Commit translated READMEs if changed
+        run: |
+          TARGETS=$(python3 -c "import json; print(' '.join(l['target'] for l in json.load(open('.github/translate/languages.json'))))")
+          git add README.md
+          for f in $TARGETS; do
+            [ -f "$f" ] && git add "$f"
+          done
+          if git diff --cached --quiet; then
+            echo "No translation changes detected."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git commit -m "docs: auto-translate README files from README.md"
+          # Retry push with rebase to handle concurrent commits
+          for i in 1 2 3; do
+            git push && exit 0
+            echo "Push failed (attempt $i/3), pulling with rebase..."
+            git pull --rebase
+          done
+          echo "Push failed after 3 attempts"
+          exit 1

package/AGENTS.md

@@ -0,0 +1,172 @@
+# AGENTS.md — MeshClaw
+
+## Project Overview
+
+MeshClaw — OpenClaw channel plugin for Meshtastic LoRa mesh networks. Enables
+sending/receiving messages over Meshtastic devices via USB serial, HTTP (WiFi), or MQTT broker.
+
+- **Language**: TypeScript (strict mode, no `tsconfig.json` — OpenClaw host loads TS via esbuild)
+- **Module system**: ESM (`"type": "module"` in package.json)
+- **Runtime**: Node.js 22+, executed by the OpenClaw plugin host (not standalone)
+- **Schema validation**: Zod v4 (not v3 — different API: `z.object().strict()`, no `.passthrough()`)
+- **Key deps**: `@meshtastic/core`, `@meshtastic/transport-http`, `@meshtastic/transport-node-serial`, `mqtt`, `zod`
+- **Repo**: `github.com/Seeed-Solution/MeshClaw` (npm: `@seeed-studio/meshtastic`)
+
+## Build / Lint / Test Commands
+
+There is **no build step, no linter, no test suite**. The plugin is loaded directly
+from TypeScript source by the OpenClaw runtime via the `openclaw.plugin.json` manifest.
+
+```bash
+npm install                                    # Install dependencies
+openclaw plugins install -l ./MeshClaw  # Install plugin locally for dev
+openclaw channels status --probe               # Verify plugin is working
+
+# Restart gateway after code changes (foreground process)
+kill -9 $(pgrep -f "openclaw-gateway" | head -1); sleep 2; openclaw gateway &
+
+# No build, lint, or test commands exist.
+# If adding tests, use vitest (ESM-native) and place tests in src/__tests__/.
+```
+
+## CI / Workflows
+
+- **Publish** (`publish.yml`): `npm publish --provenance` on `v*` tags. No build/test gate.
+- **Translate README** (`readme-translate.yml`): Translates `README.md` into 5 languages
+  (zh-CN, ja, fr, pt, es) via LLM API. Triggered by `workflow_dispatch` or `/translate`
+  comment on PRs. Config lives in `.github/translate/` (languages, glossaries, prompts).
+  Translation script: `.github/scripts/translate_readme.py` (Python, uses streaming SSE).
+
+## Project Structure
+
+```
+index.ts                  # Plugin entry — default export, registers channel with OpenClaw
+openclaw.plugin.json      # Plugin manifest (id, channels, configSchema)
+src/
+  types.ts                # Shared type definitions (config, messages, probes)
+  config-schema.ts        # Zod v4 schemas for config validation
+  runtime.ts              # Singleton plugin runtime accessor (module-level mutable ref)
+  channel.ts              # Main ChannelPlugin implementation (the "glue" file)
+  accounts.ts             # Multi-account config resolution and merging
+  client.ts               # Serial/HTTP device connection via @meshtastic/core
+  mqtt-client.ts          # MQTT broker connection via mqtt.js
+  monitor.ts              # Gateway lifecycle — starts/stops device or MQTT monitors
+  inbound.ts              # Inbound message processing (access control, routing, dispatch)
+  send.ts                 # Outbound message sending (stripMarkdown, resolves transport)
+  policy.ts               # Group/DM access policy evaluation (allowlists, mention gates)
+  normalize.ts            # Node ID normalization, target parsing, allowlist matching
+  onboarding.ts           # Interactive setup wizard integration
+.github/
+  workflows/              # CI: publish.yml, readme-translate.yml
+  scripts/                # translate_readme.py — LLM-based README translation
+  translate/              # languages.json, glossary/, prompts/, do-not-translate.md
+```
+
+## Code Style
+
+### Formatting
+
+- 2-space indentation, double quotes, semicolons always
+- Trailing commas in multi-line arrays, objects, and parameter lists
+- Soft line length ~110 characters
+- No prettier or eslint config — maintain consistency manually
+
+### Imports
+
+- **Always** use `.js` extension for local imports: `import { foo } from "./bar.js"`
+- Separate `import type` from value imports — never mix in one statement
+- Type-only imports use the `type` keyword: `import type { Foo } from "./types.js"`
+- Inline `type` keyword when mixing value + type in one import: `import { foo, type Bar } from "..."`
+
+**Import order** (blank line between groups):
+1. Node built-ins (`node:crypto`, `node:fs/promises`)
+2. Third-party packages (`@meshtastic/core`, `mqtt`, `zod`)
+3. OpenClaw SDK (`openclaw/plugin-sdk`)
+4. Local modules (`./accounts.js`, `./types.js`) — alphabetical within group
+
+### Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Files | kebab-case | `config-schema.ts`, `mqtt-client.ts` |
+| Functions | camelCase, domain-prefixed | `resolveMeshtasticAccount`, `normalizeMeshtasticNodeId` |
+| Types | PascalCase, domain-prefixed | `MeshtasticAccountConfig`, `MeshtasticTransport` |
+| Zod schemas | PascalCase, suffix `Schema` | `MeshtasticConfigSchema`, `MeshtasticAccountSchemaBase` |
+| Constants | SCREAMING_SNAKE_CASE | `CHANNEL_ID`, `MESHTASTIC_CHUNK_LIMIT` |
+| Enum-like objects | PascalCase name, `as const` | `DeviceStatus = { Connected: 5 } as const` |
+| Booleans | `is`/`has`/`was` prefix | `isGroup`, `hasConfiguredGroups`, `wasMentioned` |
+
+### Types & Type Safety
+
+- Use `type` keyword (not `interface`) for ALL type definitions
+- Shared types live in `src/types.ts`; module-local types are defined inline
+- Use `satisfies` for type narrowing without widening
+- Use `as const` for literal string constants and enum-like objects
+- **Never** suppress type errors with `as any`, `@ts-ignore`, or `@ts-expect-error`
+  - One exception: `client.ts` (`as any` in `setOwner()` for SDK compat) — avoid adding more
+
+### Function Signatures
+
+- Complex functions take a single `params` object: `function foo(params: { bar: string; baz: number })`
+- Return discriminated result objects: `{ allowed: boolean; reason: string }`
+- Optional callbacks: `onError?: (error: Error) => void`
+- Async functions return `Promise<T>` explicitly in type signatures
+
+### Error Handling
+
+- Throw plain `Error` with descriptive, user-facing messages
+- Custom error classes extend `Error` and set `this.name` (see `SetOwnerRebootError` in `client.ts`)
+- Best-effort cleanup uses empty catch: `catch { /* Best-effort cleanup */ }`
+- Error propagation via callbacks: `options.onError?.(err instanceof Error ? err : new Error(String(err)))`
+- **Never** swallow errors silently — always comment why a catch block is empty
+
+### Exports & Comments
+
+- Named exports for all functions and types
+- Single default export only in `index.ts` (the plugin entry point)
+- JSDoc `/** */` for public functions and type fields with non-obvious semantics
+- Inline `//` comments for implementation details, workarounds, and "why" explanations
+
+## Key Architecture Notes
+
+### Plugin Lifecycle
+- **Entry**: `index.ts` exports plugin object → `register()` saves runtime singleton → registers channel
+- **Runtime singleton**: `runtime.ts` holds a module-level `PluginRuntime` ref set once at registration
+- **Config flow**: YAML config → Zod v4 validation (`config-schema.ts`) → account resolution (`accounts.ts`)
+
+### Message Flow
+- **Inbound**: device/MQTT event → `monitor.ts` → `inbound.ts` (policy checks, LoRa system hint) → OpenClaw dispatch
+- **Outbound**: `send.ts` converts markdown tables → `stripMarkdown()` → resolves transport → sends via serial/HTTP/MQTT
+- **Chunking**: Outbound text chunked to ~200 bytes (`textChunkLimit`) via plain-text chunker (`chunkerMode: "text"`)
+
+### OpenClaw SDK API Patterns (CRITICAL)
+SDK pairing functions take **object params**, not positional args:
+```ts
+// CORRECT
+core.channel.pairing.readAllowFromStore({ channel: CHANNEL_ID, accountId })
+core.channel.pairing.upsertPairingRequest({ channel: CHANNEL_ID, accountId, id, meta })
+// WRONG — will cause silent failures
+core.channel.pairing.readAllowFromStore(CHANNEL_ID)
+```
+
+### Patterns to Follow
+
+- Config resolution: merge base config with per-account overrides (`mergeMeshtasticAccountConfig`)
+- Allowlist matching: normalize entries, then check `Set` membership
+- Transport abstraction: `if (transport === "serial") ... else if (transport === "http") ... else (mqtt)`
+- Module-level mutable state for active transport handles (see `send.ts`)
+- Event subscription via `device.events.onX.subscribe()` from `@meshtastic/core`
+- Promise-based blocking: `await new Promise<void>((resolve) => { signal.addEventListener("abort", resolve) })`
+- Reconnect resilience: catch + disconnect + rethrow pattern in `client.ts`
+- LoRa outbound: always `stripMarkdown()` before sending — radio can't render formatting
+
+### Patterns to Avoid
+
+- Don't add build steps — the OpenClaw runtime loads TS directly
+- Don't add new dependencies without strong justification
+- Don't create classes unless modeling errors — prefer plain functions and objects
+- Don't use `interface` — use `type` for consistency
+- Don't use barrel exports (`index.ts` re-exporting everything from `src/`)
+- Don't add `console.log` — use the runtime logger (`core.logging.getChildLogger()`)
+- Don't assume SDK functions take positional args — always check the `.d.ts` signatures
+- Don't send markdown-formatted text to the radio — LoRa devices display raw characters

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Seeed Solution
+
+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.