grok-gadgets-linux-sdk 0.1.0a5__tar.gz

grok_gadgets_linux_sdk-0.1.0a5/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Prepared ownership; enforcement activates only after approved publication.
+* @adidshaft

grok_gadgets_linux_sdk-0.1.0a5/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,43 @@
+name: Bug report
+description: A reproducible failure, with redacted evidence
+labels:
+- bug
+body:
+- type: input
+  id: version
+  attributes:
+    label: Version or full source commit
+  validations:
+    required: true
+- type: input
+  id: host
+  attributes:
+    label: Component, OS and runtime
+  validations:
+    required: true
+- type: dropdown
+  id: evidence
+  attributes:
+    label: Test environment
+    options:
+    - Browser simulation
+    - Local MCP / software device
+    - Compiled firmware only
+    - Physical hardware
+    - Actual Grok client
+    - Home Assistant installation
+  validations:
+    required: true
+- type: textarea
+  id: reproduce
+  attributes:
+    label: Steps, expected behavior and observed result
+  validations:
+    required: true
+- type: textarea
+  id: logs
+  attributes:
+    label: Redacted logs or evidence
+    description: Never include tokens, account details, household names or private endpoints.
+  validations:
+    required: false

grok_gadgets_linux_sdk-0.1.0a5/.github/ISSUE_TEMPLATE/compatibility.yml

@@ -0,0 +1,18 @@
+name: Compatibility report
+description: Report a reproducible SDK compatibility issue without private home data
+title: "[compatibility] "
+labels: [bug, linux]
+body:
+  - type: textarea
+    id: environment
+    attributes:
+      label: Versions and evidence level
+      description: SDK/gateway versions, OS/kernel, transport, simulation or real peripheral; omit tokens and household names.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction and expected behavior
+    validations:
+      required: true

grok_gadgets_linux_sdk-0.1.0a5/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+- name: Questions and build discussion
+  url: https://www.reddit.com/r/GrokGadgets/
+  about: Questions do not require a full bug form.
+- name: Private security or conduct report
+  url: mailto:adidshaft@kyokasuigetsu.xyz
+  about: Use the private contact. GitHub private reporting activation is pending.

grok_gadgets_linux_sdk-0.1.0a5/.github/ISSUE_TEMPLATE/documentation.yml

@@ -0,0 +1,24 @@
+name: Documentation improvement
+description: Help make a setup or explanation clearer
+labels:
+- docs
+body:
+- type: input
+  id: page
+  attributes:
+    label: Page or source file
+  validations:
+    required: true
+- type: textarea
+  id: confusion
+  attributes:
+    label: Attempted step and what was confusing
+  validations:
+    required: true
+- type: textarea
+  id: suggestion
+  attributes:
+    label: Suggested improvement
+    description: An exact proposal is helpful but optional.
+  validations:
+    required: false

grok_gadgets_linux_sdk-0.1.0a5/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,24 @@
+name: Feature proposal
+description: A bounded use case and compatibility impact
+labels:
+- feature
+body:
+- type: textarea
+  id: usecase
+  attributes:
+    label: Use case and affected component
+  validations:
+    required: true
+- type: textarea
+  id: behavior
+  attributes:
+    label: Proposed behavior and scope
+  validations:
+    required: true
+- type: textarea
+  id: compatibility
+  attributes:
+    label: Compatibility and evidence needed
+    description: Discuss protocol/API changes before implementation.
+  validations:
+    required: true

grok_gadgets_linux_sdk-0.1.0a5/.github/ISSUE_TEMPLATE/hardware.yml

@@ -0,0 +1,31 @@
+name: Hardware verification report
+description: Actual observations from an identified device
+labels:
+- needs hardware
+body:
+- type: input
+  id: model
+  attributes:
+    label: Exact model and firmware source/hash
+  validations:
+    required: true
+- type: input
+  id: host
+  attributes:
+    label: Host, runtime and cable/transport
+  validations:
+    required: true
+- type: textarea
+  id: steps
+  attributes:
+    label: Steps and expected/observed results
+    description: Separate firmware acknowledgement from physical observation; include disconnect/recovery.
+  validations:
+    required: true
+- type: textarea
+  id: evidence
+  attributes:
+    label: Safe redacted evidence
+    description: Do not include private device identifiers or account details.
+  validations:
+    required: false

grok_gadgets_linux_sdk-0.1.0a5/.github/dependabot.yml

@@ -0,0 +1,21 @@
+# Weekly version updates, grouped per ecosystem, opened as PRs into dev.
+# Security-update PRs ignore target-branch and open against main; retarget them
+# to dev before merging. Triage rules: https://github.com/adidshaft/grok-gadgets/blob/dev/SECURITY.md
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    target-branch: dev
+    schedule:
+      interval: weekly
+    groups:
+      python:
+        patterns: ["*"]
+  - package-ecosystem: github-actions
+    directory: /
+    target-branch: dev
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]

grok_gadgets_linux_sdk-0.1.0a5/.github/pull_request_template.md

@@ -0,0 +1,21 @@
+<!-- main is the default branch for users, builders and the website. Development and testing integrate on dev. Ordinary contribution PRs target dev; main accepts release and hotfix PRs only. Verify the base branch before submitting. -->
+
+## Problem and resulting behavior
+
+<!-- Concrete before/after behavior and scope. -->
+
+## Issue and changes
+
+<!-- Link the issue or stable local ID. Small typo fixes need no new issue. -->
+
+## Checks and evidence
+
+<!-- Commands and actual results; distinguish simulation, compilation, native Grok and physical observation. -->
+
+## Documentation, compatibility and remaining limitations
+
+<!-- Pin/schema changes, recovery and unresolved gates. Redact private information. -->
+
+## Checklist
+
+- [ ] The base is `dev` for an ordinary contribution, or `main` for a release or hotfix.

grok_gadgets_linux_sdk-0.1.0a5/.github/workflows/checks.yml

@@ -0,0 +1,80 @@
+name: Checks
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: '41 5 * * *'
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: checks-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  linux-sdk-checks-matrix:
+    name: linux-sdk-checks (${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12', '3.13', '3.14']
+    defaults:
+      run:
+        working-directory: grok-gadgets-linux-sdk
+    env:
+      # The seven gateway integration tests run against gateway main, never skip.
+      GROK_GATEWAY_SOURCE: ${{ github.workspace }}/grok-gadgets-gateway/src
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          path: grok-gadgets-linux-sdk
+          persist-credentials: false
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: adidshaft/grok-gadgets-gateway
+          ref: main
+          path: grok-gadgets-gateway
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          version: '0.12.3'
+      - run: uv sync --frozen --extra gateway --python ${{ matrix.python-version }}
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - name: Plain language (ASD-STE100 sentence limit)
+        run: python3 scripts/check_ste.py README.md CONTRIBUTING.md SUPPORT.md
+      - name: Unit and gateway-main integration tests
+        run: |
+          git -C ../grok-gadgets-gateway log -1 --format='Gateway main %H'
+          uv run python -m unittest discover -s tests -v 2>&1 | tee "$RUNNER_TEMP/tests.log"
+          if grep -q "skipped 'Set GROK_GATEWAY_SOURCE\|skipped 'Install the \[gateway\]" "$RUNNER_TEMP/tests.log"; then
+            echo "Gateway integration tests skipped" >&2; exit 1
+          fi
+        timeout-minutes: 5
+      - run: uv build
+      - name: Package metadata renders on PyPI (nothing is uploaded)
+        run: uvx --from 'twine==7.0.0' twine check --strict dist/*
+  readme-quickstart:
+    # The README quick start in a fresh clone (install, my_gadget.py, dev), then a real MCP call.
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          version: '0.12.3'
+      - run: python3 scripts/check_readme_quickstart.py
+  linux-sdk-checks:
+    name: linux-sdk-checks
+    if: always()
+    needs: [linux-sdk-checks-matrix, readme-quickstart]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require every Python version and the README quick start
+        env:
+          MATRIX_RESULT: ${{ needs.linux-sdk-checks-matrix.result }}
+          QUICKSTART_RESULT: ${{ needs.readme-quickstart.result }}
+        run: test "$MATRIX_RESULT" = success && test "$QUICKSTART_RESULT" = success

grok_gadgets_linux_sdk-0.1.0a5/.github/workflows/pr-target.yml

@@ -0,0 +1,25 @@
+name: PR target
+# main holds releases only. A PR into main must come from this repository's dev branch
+# (a release) or a hotfix/* branch. Everything else belongs in dev.
+on:
+  pull_request:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  pr-target:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Release or hotfix branches only
+        env:
+          HEAD_REF: ${{ github.head_ref }}
+          HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
+        run: |
+          if [ "$HEAD_REPO" = "$GITHUB_REPOSITORY" ]; then
+            case "$HEAD_REF" in
+              dev|hotfix/*) echo "OK: $HEAD_REF may target main."; exit 0 ;;
+            esac
+          fi
+          echo "::error::Pull requests into main are for releases (from dev) and hotfixes (hotfix/* branches) only. Please change the base branch to dev." >&2
+          exit 1

grok_gadgets_linux_sdk-0.1.0a5/.github/workflows/release.yml

@@ -0,0 +1,102 @@
+name: release packages
+# Started by hand for one tag; nothing runs on push. It builds once, writes SHA256SUMS with
+# plain file names, checks it in a fresh folder, and attaches the files to the tag's GitHub
+# release. With publish_pypi it also uploads to PyPI through trusted publishing (OIDC): no
+# token is stored. The `pypi` environment can require the owner's approval.
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing release tag, for example v0.1.0-alpha.7
+        required: true
+      publish_pypi:
+        description: Also upload to PyPI
+        type: boolean
+        default: false
+permissions:
+  contents: read
+concurrency:
+  group: release-${{ inputs.tag }}
+  cancel-in-progress: false
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: refs/tags/${{ inputs.tag }}
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          version: '0.12.3'
+      - name: Tag matches the package version
+        env:
+          TAG: ${{ inputs.tag }}
+        run: |
+          python3 - <<'PY'
+          import os, re, tomllib
+          version = tomllib.load(open("pyproject.toml", "rb"))["project"]["version"]
+          tag = os.environ["TAG"]
+          match = re.fullmatch(r"v(\d+\.\d+\.\d+)(?:-(alpha|beta|rc)\.(\d+))?", tag)
+          short = {"alpha": "a", "beta": "b", "rc": "rc"}
+          expected = match and match[1] + (short[match[2]] + match[3] if match[2] else "")
+          if expected != version:
+              raise SystemExit(f"Tag {tag} does not match version {version}")
+          PY
+      - run: uv build --out-dir dist
+      - name: Package metadata renders on PyPI
+        run: uvx --from 'twine==7.0.0' twine check --strict dist/*
+      - name: Write SHA256SUMS with plain file names
+        run: |
+          mkdir sums
+          (cd dist && sha256sum -- *.whl *.tar.gz) > sums/SHA256SUMS
+          cat sums/SHA256SUMS
+      - name: Check SHA256SUMS in a fresh folder, as a downloader would
+        run: |
+          mkdir fresh
+          cp dist/* sums/SHA256SUMS fresh/
+          cd fresh && sha256sum -c SHA256SUMS
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: sums
+          path: sums/
+          if-no-files-found: error
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          path: assets
+          merge-multiple: true
+      - name: Attach to the existing release (never replaces an asset)
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          TAG: ${{ inputs.tag }}
+        run: gh release upload "$TAG" assets/*
+  pypi:
+    if: inputs.publish_pypi
+    needs: [build, github-release]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/grok-gadgets-linux-sdk/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

grok_gadgets_linux_sdk-0.1.0a5/.gitignore

@@ -0,0 +1,43 @@
+# Local configuration and credentials. Commit only reviewed, non-secret examples.
+.env
+.env.*
+!.env.example
+!.env.sample
+!.env.template
+credentials*.json
+!credentials.example.json
+secrets*.json
+secrets*.yaml
+secrets*.yml
+secrets.h
+.secrets/
+*.pem
+*.key
+*.p12
+*.pfx
+my-light.json
+my_gadget.py
+fresh-run.jsonl
+
+# Environments, caches and generated output.
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage*
+htmlcov/
+*.egg-info/
+node_modules/
+dist/
+build/
+.pio/
+/artifacts/
+/reports/
+*.log
+
+# Operating-system files.
+.DS_Store
+Thumbs.db

grok_gadgets_linux_sdk-0.1.0a5/AGENTS.md

@@ -0,0 +1,17 @@
+# Repository instructions
+
+Own reusable Linux library, agent and examples here. Consume the pinned canonical protocol from the gateway repository's protocol/0.1.0 and communicate breaking changes before adopting them. Prepared upstream: https://github.com/adidshaft/grok-gadgets-gateway. No conflicting schema definitions. Keep host/runtime evidence explicit; macOS does not verify Linux. Use subagents when useful; never Brave/Safari/Passwords. No push/publication/deployment/spending/live devices without authorization.
+
+Use main and short feature branches with small tested commits referencing planning/issues.json. Maintain issues and respond when remote publication is authorized. Checks: uv sync --frozen; uv run ruff check .; uv run ruff format --check .; uv run python -m unittest discover -s tests -v; uv build. Never commit credentials or imply execution proves physical effects.
+
+Use bounded subagents with explicit file ownership when helpful. Research tasks use the
+strongest available reasoning and cite primary sources. Report any gap before substituting.
+
+**Grok Bot only.** The product, its docs, website, examples, tests, commits and branch names
+describe Grok Bot and SpaceXSI technology as the only assistant platform. Do not name,
+recommend or credit other AI assistants, models, chat products, coding agents or editors
+anywhere in the repository. Development tooling stays out of the record.
+
+## Ignore rules and publication privacy
+
+Keep `.gitignore` current whenever a new tool produces caches, build output, local device configurations, execution logs or credentials. Preserve reviewed sample configuration files and the hub's verified public simulator download. Check new patterns with `git check-ignore`, then review the staged file list before committing. Ignore rules do not remove tracked files or past history; never merge the private pre-publication history back into a public branch. Use the sanitized public checkout and a public or GitHub noreply commit email.

grok_gadgets_linux_sdk-0.1.0a5/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0-alpha.5 — 12 October 2026
+
+- `grok-linux-agent --version` prints the SDK version and exits without connecting ([#16](https://github.com/adidshaft/grok-gadgets-linux-sdk/issues/16)).
+- The `gateway` extra and lockfile pin gateway v0.1.0-alpha.7, so the extra names a version that the gateway's own release workflow can publish to PyPI.
+- A hand-started **release packages** workflow builds a tag, writes `SHA256SUMS` with plain file names, checks it in a fresh folder and attaches the files to the release. PyPI upload is a separate opt-in through trusted publishing; no token is stored ([#61](https://github.com/adidshaft/grok-gadgets-linux-sdk/issues/61), hub [#151](https://github.com/adidshaft/grok-gadgets/issues/151)). The package is not on PyPI yet.
+- README adds pip install from the release wheel. Homepage is https://grokgadgets.org/. Docs match the 12 October evidence.
+
+## 0.1.0-alpha.4 — 8 October 2026
+
+- Pin the gateway extra and lockfile to gateway v0.1.0-alpha.4, which uses `mcp` 2.3.0. The README quick-start check uses the `mcp` 2.x HTTP client.
+- Development tools: `ruff` 0.16.10 and `hatchling` 1.32.4. Code follows the new `ruff` default rules without behavior changes. CI checks packages with `twine` 7.0.0, which reads the Metadata-Version 2.5 that `hatchling` 1.32 writes.
+
+## 0.1.0-alpha.3 — 8 October 2026
+
+- Security: pin the gateway extra and lockfile to gateway v0.1.0-alpha.3. This moves `mcp` from 1.26.0 to 1.28.1 and closes its high-severity Dependabot alerts.
+- Dependabot opens weekly grouped update PRs into `dev`.
+- CONTRIBUTING starts fork branches from `upstream/dev`. CI also runs the plain-language check on CONTRIBUTING and SUPPORT.
+
+## 0.1.0-alpha.2 — 7 October 2026
+
+- Pin the gateway extra and lockfile to gateway v0.1.0-alpha.2.
+- Add a runnable Grok Bot rehearsal step to the README quick start.
+
+## 0.1.0a1 — 6 October 2026
+
+- Pin the gateway dependency to its `v0.1.0-alpha.1` release tag.
+- `grok-linux-agent dev ./my_gadget.py` runs your gadget with an in-process gateway and loopback auto-trust: no tokens to copy. It prints pasteable MCP settings (stdio needs no token at all). Needs the new `[gateway]` extra (`uv sync --extra gateway`; the gateway comes from its GitHub repository until it is on PyPI).
+- `--token-file <path>` reads a private device token and re-reads it on every connection, so `grok-gadgets-gateway enroll <id> --rotate --token-file <path>` needs no agent restart. `--factory-file` accepts a plain gadget file.
+- README: the quick start is one install, one ten-line file and one command.
+- New decorator API: `Gadget(...)` with `@gadget.command("What it does")`. The JSON schema comes from type hints (`bool`, `int`, `float`, `str`, `Literal`, `list`, optional, `Annotated` with `Range`). `Device.capability` keeps working and gains `description=`; `event_capability` too.
+- Capability descriptions reach the assistant (gateway `capability_descriptions`). A TCP hello may be up to 16 KiB; other frames stay 2048 bytes. Protocol README re-pinned from gateway `3e41aec`.
+- Re-pin the protocol 0.1.0 README from gateway `c568c3e` (sections and `late_ack`; wire format unchanged). With `GROK_GATEWAY_SOURCE`, a test checks the copied protocol files match that gateway.
+- A handler that overruns `handler_timeout` now gets a `failed` ACK (`handler_timeout`) and the session stays open; a replay of that command ID reports the same failure.
+- `late_ack` and `unknown_command` replies to an ACK are non-fatal: the agent drops that ACK and keeps polling instead of reconnecting.
+- CI runs the seven gateway integration tests against gateway `main` and fails if they skip. A new job runs the README quick start in fresh clones and calls the gadget over MCP. Both run on push, pull request and nightly.
+
+## 0.1.0a1 — unpublished
+
+Generic capability SDK and loopback agent with strict pinned contracts, bounded retries,
+safe errors, and explicit trusted-file factories (including annotated dataclasses).
+Installed software acceptance is recorded on macOS arm64 and Linux aarch64 in a pinned
+container. Physical peripherals, real systemd behavior, native Grok/mobile evidence,
+and independent human reproduction remain pending.
+
+### Review fixes, 2026-10-05 — unpublished
+
+- A reused command ID with changed arguments returns a failed `duplicate_conflict`
+  acknowledgement and keeps the session; replays report current state.
+- State is limited so every acknowledgement fits one 2048-byte frame (closes the
+  AUDIT-LIN-001 edge); deeply nested replies are `invalid_response`.
+- Custom event names carry `x-grok-gadgets-kind: event`; `history_lost` is reserved.
+- Plain-function handlers run in a worker thread; new `Device.on_shutdown(callback)`.
+- SIGTERM/SIGINT cancel the running handler and run shutdown hooks; one transient
+  `unauthorized` after a successful hello is retried; jittered backoff;
+  `--max-attempts` and `--retry-forever`; distinct exit codes 2/3/4/5.
+- `GROK_GADGETS_DEVICE_TOKEN` replaces `GROK_DEVICE_TOKEN` (deprecated fallback).
+- Usable systemd user-unit template; CI matrix for Python 3.11–3.14.
+- Plain-language README; corrected evidence labels and security limits.
+
+### Launch preparation, 2026-10-05 — unpublished
+
+- Add a standalone fresh-wheel custom-device journey, architecture diagram, and runtime/evidence table.
+- Expand contribution/support/conduct/security guidance and prepare `adidshaft` ownership.
+- Preserve SDK runtime, canonical protocol pins, Apache-2.0 license, and notices.

grok_gadgets_linux_sdk-0.1.0a5/CODE_OF_CONDUCT.md

@@ -0,0 +1,15 @@
+# Code of conduct
+
+The canonical [Grok Gadgets policy](https://github.com/adidshaft/grok-gadgets/blob/main/CODE_OF_CONDUCT.md)
+applies to SDK issues, pull requests, reviews, and project spaces. The link is a planned
+destination until approved activation; these rules also apply during local preparation.
+
+Be respectful, constructive, and inclusive. Critique behavior and code, not people.
+Harassment, threats, discrimination, unwanted contact, and disclosure of someone else's
+private information are unacceptable. Respect stated boundaries and reviewers' time.
+
+Report concerns privately to **adidshaft@kyokasuigetsu.xyz**. **@adidshaft** is initially
+responsible; no additional moderation team is implied. Share only what is needed to investigate.
+Responses may include correction, warning, temporary restriction, or removal, proportionate
+to conduct and repetition. Appeal through the same email with the decision and context;
+the maintainer will reconsider it. No confidentiality guarantee or response SLA is invented.

grok_gadgets_linux_sdk-0.1.0a5/CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing to the Linux SDK
+
+Contribute to the library, agent, examples, tests or documentation without hardware. Device handlers belong here. The gateway owns the canonical protocol and MCP routing.
+
+Discuss large features, interface changes and protocol changes before implementation. Submit small typo fixes directly. Use the [writing guide](https://github.com/adidshaft/grok-gadgets/blob/main/docs/contributing/writing-guide.md) for documentation.
+
+The hub owns [shared contribution policy](https://github.com/adidshaft/grok-gadgets/blob/main/CONTRIBUTING.md),
+[governance](https://github.com/adidshaft/grok-gadgets/blob/main/GOVERNANCE.md), and
+[roadmap](https://github.com/adidshaft/grok-gadgets/blob/main/ROADMAP.md). Use [GitHub Issues](https://github.com/adidshaft/grok-gadgets-linux-sdk/issues) to track current work. The [local issue ledger](planning/issues.json) records preparation work.
+
+## Standalone checks
+
+Use Python 3.11 or later and uv. CI runs the same sequence on Python 3.11, 3.12, 3.13 and 3.14. Fork the repository and clone your fork. A fork can hold only `main`, so start your branch from the upstream `dev`:
+
+```sh
+git clone https://github.com/YOUR_ACCOUNT/grok-gadgets-linux-sdk.git
+cd grok-gadgets-linux-sdk
+git remote add upstream https://github.com/adidshaft/grok-gadgets-linux-sdk.git
+git fetch upstream dev
+git switch -c docs/LIN-123-clearer-device-example upstream/dev
+uv sync --frozen --extra gateway --python 3.11
+uv run ruff check .
+uv run ruff format --check .
+uv run python -m unittest discover -s tests -v
+uv build
+```
+
+These checks need no sibling checkout. Without `GROK_GATEWAY_SOURCE`, seven gateway integration tests skip locally. CI never skips them: it runs them against gateway `main` on every push, pull request and night. CI also runs the README quick start in fresh clones with `python3 scripts/check_readme_quickstart.py` (commit first; it clones `HEAD`). Each integration test has a time limit, so a hang is reported as a failure.
+
+For runtime or protocol changes, use a reviewed gateway source checkout:
+
+```sh
+GROK_GATEWAY_SOURCE=/absolute/path/grok-gadgets-gateway/src uv run python -m unittest discover -s tests -v
+```
+
+Replace the placeholder with the checkout at the exact agreed commit. Record both SHAs.
+The hub separately tests the coordinated component combination; an isolated SDK success
+does not promote it automatically.
+
+For example, factory-loading, or installation guidance changes, also run the fresh-wheel
+onboarding from an empty folder outside the checkout. Put the SDK wheel and sdist and the
+gateway wheel in that folder, then run:
+
+```sh
+uv venv --python 3.11 --seed .venv
+.venv/bin/python -m pip install ./grok_gadgets_linux_sdk-0.1.0a1-py3-none-any.whl ./grok_gadgets_gateway-0.1.0a1-py3-none-any.whl
+tar -xzf grok_gadgets_linux_sdk-0.1.0a1.tar.gz
+.venv/bin/python -I grok_gadgets_linux_sdk-0.1.0a1/scripts/check_onboarding.py grok_gadgets_linux_sdk-0.1.0a1/docs/development.md
+```
+
+It runs the documented `my_gadget.py` with `--factory-file` against an authenticated
+loopback gateway and prints `"ack": "executed"`. Run the lint/format/unit/build checks
+before committing documentation as well as code. Linux service/peripheral claims need
+their own authorized Linux/hardware observations.
+
+## Branches
+
+Branch from `dev` and open your PR into `dev` for integration, development and testing; PRs into `dev` are squash-merged when checks pass. `main` is the default branch for users, builders and the website, holds tagged releases, and changes only through release or hotfix PRs. Name branches `<type>/<ISSUE-ID>-<short-slug>`, for example `fix/LIN-021-short-name`. The shared [branch and release policy](https://github.com/adidshaft/grok-gadgets/blob/main/CONTRIBUTING.md#branches-and-releases) covers releases, hotfixes and cross-repository changes.
+
+Push the branch to your fork and open the PR into `adidshaft/grok-gadgets-linux-sdk` `dev`. The GitHub PR form selects `main` by default. Change the base branch to `dev`, because the PR-target check rejects other PRs into `main`.
+
+## Review and credit
+
+Use a short branch from `dev`. Make small tested commits and link the public issue. Explain the behavior before and after the change. Add a regression test when necessary.
+
+Record commands, results, runtime and evidence level. Update user guidance. Respond to review and resolve conflicts on your branch. Then repeat affected checks.
+
+Handlers must validate arguments and report observed state. Preserve retry, reconnect,
+bounded retention, and safe-error behavior. Protocol changes start upstream and require
+renewed canonical pins/hashes plus hub compatibility evidence; never hand-edit schema copies.
+
+The maintainer credits code, documentation, testing, and review. You remain responsible
+for AI-assisted contributions, licenses, and verified test claims. Contributions use
+Apache-2.0; no additional CLA or sign-off is required. Never include credentials or private
+captures. Do not publish, deploy, or operate live peripherals in an unapproved test.
+
+See [support](SUPPORT.md), [conduct](CODE_OF_CONDUCT.md), [security](SECURITY.md), and [AGENTS](AGENTS.md).
+
+## Ignore rules and publication privacy
+
+Update `.gitignore` for new caches, build output, local device configuration, logs and credentials. Keep reviewed sample configuration and the hub’s public simulator download.
+
+Check new patterns with `git check-ignore`. Review staged files before each commit. Ignore rules do not remove tracked files or history. Never merge private pre-publication history into a public branch. Use the sanitized public checkout and a public or GitHub noreply commit email.
+
+## Documentation style
+
+Use ASD-STE100-inspired English. This project does not claim certified compliance.
+Use active verbs, short sentences and one instruction per numbered step.
+Keep technical names, commands and quoted evidence exact. Explain each new technical term.
+Separate current instructions from dated test records. Link to evidence before you claim a test passed.
+Run the repository's plain-language check on each changed guide. It checks sentence length, not the full standard.