onde-cli 0.3.1__tar.gz → 0.4.0__tar.gz

onde_cli-0.4.0/.agents/AGENTS.md

@@ -0,0 +1,69 @@
+# AGENTS.md
+
+`onde-cli` is a Rust TUI (`onde` binary) for managing an Onde Inference account and running a local model pipeline: LoRA fine-tune → adapter merge → GGUF export → local chat test → Hugging Face upload → model assignment to an Onde app. npm, PyPI, NuGet, pub.dev, Homebrew, and crates.io are thin wrappers around this one binary; the Rust crate is the source of truth.
+
+## Build, test, lint
+
+```sh
+cargo build                  # debug build
+cargo run                    # launch the TUI
+cargo run -- --mcp           # run as an MCP server over stdio (no TUI)
+cargo test --locked          # unit tests (heavy ones are #[ignore])
+cargo clippy --all-targets -- -D warnings
+cargo fmt -- --check
+```
+
+The build **requires** these env vars (read from `.env` via `build.rs`): `ONDE_APP_ID`, `ONDE_APP_SECRET`, `GRESIQ_API_KEY`, `GRESIQ_API_SECRET`. `HF_TOKEN` is optional. They are baked in at compile time via `env!(...)` in `src/app.rs`. Changing `.env` triggers a full rebuild.
+
+On macOS, candle's `metal` + `accelerate` features are added automatically. **Fine-tuning always runs on CPU** — Metal's backward pass in candle 0.10.2 produces corrupt gradients (1e6–1e29 in magnitude, where CPU gives ~40–65 for identical losses). Use `ONDE_FINETUNE_METAL=1` only to test newer candle versions, and verify with `ONDE_FINETUNE_GRAD_DEBUG=1` (per-step loss/max_abs/norm).
+
+Linux CI requires `libclang-dev` (`sudo apt-get install -y libclang-dev`).
+
+### Tests that load real models
+
+`src/gguf.rs` has two `#[ignore]` integration tests that export a ~1GB GGUF and run inference through `onde::mistralrs`. They need a Qwen3-0.6B model cached in the Onde App Group container and skip gracefully when it is absent.
+
+```sh
+cargo test gguf::tests::exported_qwen3_gguf_is_runnable -- --ignored --nocapture
+cargo test gguf::tests::finetune_merge_export_run     -- --ignored --nocapture
+```
+
+Env knobs for these: `ONDE_TEST_MODEL_DIR`, `ONDE_TEST_DTYPE` (`f16`/`q8_0`), `ONDE_TEST_LR`, `ONDE_TEST_DATA_PATH`, `ONDE_TEST_EPOCHS`, `ONDE_TEST_MAX_SEQ_LEN`, `ONDE_TEST_EVAL_PROMPT` (`||`-separated prompts), `ONDE_TEST_SYSTEM_PROMPT`. This makes the full-pipeline test double as a headless fine-tune runner for a custom dataset.
+
+### Debugging the TUI
+
+`main.rs` redirects both stdout and stderr to `~/.cache/onde/debug.log` before ratatui takes the alternate screen, because `mistral.rs` writes to both fds and would otherwise tear up the display. To see what the app or the inference engine is doing, tail that log; `println!`/`eprintln!`/`log::*` all land there, not on screen.
+
+## Architecture — `src/`
+
+| File(s) | Responsibility |
+|---|---|
+| `main.rs` | Entry point; redirects stdout/stderr to `~/.cache/onde/debug.log` before ratatui takes over |
+| `app.rs` | `App` struct + `Screen` state machine + `AuthEvent` channel (`tokio::select!` over an `mpsc` channel and a `crossterm` `EventStream`); `App::apply` folds background progress into state |
+| `ui.rs` | Pure ratatui render of `App`; no SDK imports (re-exports types through `app.rs`) |
+| `finetune.rs` | Hand-written LoRA trainer (candle, CPU): Qwen forward pass (RMSNorm, RoPE, GQA, optional Qwen3 QK-norm), LoRA A/B trained on q/v projections in F32, writes `lora_adapter.safetensors`. Gradients are sanitized (non-finite elements zeroed) and globally norm-clipped in a scaled space before each AdamW step; a step is skipped (loudly) only when the norm is zero or non-finite. **Skipping this guard corrupts every weight after the first bad step.** |
+| `merge.rs` | Folds LoRA adapter into base weights (`W + scale·(B@A)`); writes `model.safetensors` plus copied config/tokenizer |
+| `gguf.rs` | Hand-rolled GGUF writer (no llama.cpp). Tensor dims are written innermost-first — reverse of safetensors shape, because candle reverses on read; `head_dim` comes from config and is emitted as `attention.key_length`/`value_length` (Qwen3 decouples it from `hidden_size/num_heads`); `token_type` is an INT32 array; `general.architecture` is chosen from `model_type` so Qwen3 routes to candle's `quantized_qwen3` loader |
+| `chat.rs` | Local GGUF chat via `onde::mistralrs::GgufModelBuilder`, the same engine the Onde SDK uses, so a model can be tested before publishing |
+| `hf_upload.rs` / `hf_clone.rs` / `hf_search.rs` / `hf.rs` | Hugging Face Hub: upload the GGUF, check/create a repo, search models, and resolve/merge the local HF cache (incl. the macOS Onde App Group container) |
+| `gresiq.rs` | `smbcloud-gresiq-sdk` wrapper for apps and the model catalog. "Deploying" a model means `assign_model(app_id, model_id)` against a catalog entry; the end app then fetches that assignment through the Onde SDK's `load_assigned_model` and downloads the GGUF. The CLI can only assign models that already exist in the GresIQ catalog |
+| `token.rs` | Auth token persistence |
+| `project.rs` | Per-project fine-tune workspaces under `~/.onde` |
+
+**Background task rule:** network/IO → `tokio::spawn`; CPU-heavy tensor work (`finetune`, `merge`, `gguf`) → `std::thread::spawn` to avoid starving the async runtime.
+
+**Adding a feature pattern:** new `Screen` variant → key handler → `AuthEvent` variant → background task that streams progress events.
+
+### The `onde` dependency
+
+The `onde` crate provides the inference engine (`onde::mistralrs`, a vendored mistral.rs) and `onde::inference::models::SUPPORTED_MODEL_INFO` (the supported-model catalog the inference picker mirrors). It is normally the published crate; `Cargo.toml` has commented `path`/`[patch.crates-io]` blocks for developing against local checkouts of `onde`, the `smbcloud-*` crates, and `candle` — never commit with those uncommented.
+
+## Conventions
+
+- **Git:** merge feature/release/hotfix branches with `--no-ff`. Tag the merge commit on `main`. Never tag a branch tip that hasn't been merged. See `.agents/skills/git/SKILL.md`.
+- **Commits:** include `Co-Authored-By: siGit Code <297239231+sigitc@users.noreply.github.com>` trailer when committing with the agent.
+- **`[patch.crates-io]` and `path =` deps:** commented out in `Cargo.toml` for local dev against `onde`/`smbcloud-*`/`candle`. Never commit with these uncommented.
+- **Distribution:** before touching any wrapper package (npm, PyPI, NuGet, pub.dev, Homebrew), read `.agents/skills/distribution/SKILL.md`. Keep all channel versions aligned with the Rust crate version in `Cargo.toml`.
+- **Wrapper packages** are in `npm/`, `pypi/`, `nuget/`, `pub/`. The npm base manifest is rewritten at release time by `npm/scripts/render-main-package.cjs`; do not hand-edit committed package.json versions as the source of truth for releases.
+- **Clippy** runs with `-D warnings` in CI; all lints must pass.
+- **Rust edition:** 2024; toolchain: stable.

{onde_cli-0.3.1 → onde_cli-0.4.0}/.agents/skills/distribution/SKILL.md

@@ -82,14 +82,16 @@ Good fit for .NET developers and CI environments that already use `dotnet tool i
 
 ### pub.dev
 
-Use a Dart package with a command entrypoint and a library that launches the bundled native binary.
+Use a Dart package with a command entrypoint and a library that launches the native binary.
 
 Important details:
 
 - executable command should stay `onde`
-- use `Isolate.resolvePackageUri` to find the installed package path
 - keep the runtime-id mapping explicit
-- do not overcomplicate the wrapper with platform-specific Dart APIs unless necessary
+- download the correct binary from GitHub Releases on first run
+- cache downloads under `~/.onde/cli`
+- keep the wrapper thin, the Rust binary is still the product
+- publish the pub.dev package only after the matching GitHub Release exists
 
 Good fit for Dart and Flutter developers who want the same CLI through familiar tooling.
 
@@ -141,14 +143,18 @@ Safer checks:
 
 pub.dev behaves differently from npm and NuGet in one important way:
 
-- files ignored by git are generally excluded from publish input
+- large bundled binaries quickly hit package size limits
 
-That means staged native binaries for `pub/onde_cli/native/` must be available to the package at publish time.
+That makes the safest design a thin Dart launcher that downloads the right native binary from GitHub Releases at runtime instead of shipping every platform binary inside the package.
 
-Two practical consequences:
+Practical consequences:
 
-- do not ignore `pub/onde_cli/native/` in the root `.gitignore` if CI stages binaries there
-- a `.pubignore` can hide local tool noise, but do not hide the native payload you intend to publish
+- `pub/onde_cli/native/` should stay out of the published package
+- do not set `publish_to: https://pub.dev` in `pubspec.yaml`; omit `publish_to` for normal pub.dev publishing
+- use package-level ignore rules so local native staging does not leak into publish input
+- keep release asset names aligned with the GitHub Release workflow, because the launcher depends on them
+- treat `~/.onde/cli` as the local cache root for downloaded binaries
+- do not let the pub.dev workflow race ahead of GitHub Releases; dispatch it after `release-github.yml` has created the assets
 
 Run these during verification:
 
@@ -211,7 +217,9 @@ At minimum, check:
 - manually bumping the committed npm manifest and assuming that is what npm publishes
 - staged native binaries land in the wrong directory before packaging
 - package builds successfully but installs without the native binary
-- pub.dev package omits staged assets because gitignore excludes them
+- pub.dev launcher points at the wrong GitHub Release asset name or runtime id
+- pub.dev workflow publishes before the matching GitHub Release assets exist
+- pub.dev package still includes bundled binaries and blows the upload size limit
 - smoke test invokes a TUI-first binary in a way that does not make sense for CI
 - README badges and install commands drift out of sync with real package names
 

onde_cli-0.4.0/.agents/skills/git/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: git
+description: Git workflow rules for this repository.
+allowed-tools: Read, Write, Edit, Glob, Grep, AskUserQuestion
+user-invocable: true
+---
+
+# Git skill
+
+## Core rule
+
+- Use `--no-ff`. Important.
+
+## What this means in practice
+
+- Do not fast-forward merge feature branches, release branches, or hotfix branches.
+- Prefer explicit merge commits so the branch history stays visible.
+- Release prep goes through `development` on its way to `main`, with `--no-ff` at every hop.
+- Tag the merge commit that contains the final release state.
+
+## Branch flow
+
+Feature branches merge into `development`. Releases go:
+
+```
+release/vX.Y.Z -> development -> main
+```
+
+Never merge a release branch straight into `main` — `development` has to carry the
+release state too, or the next feature branch starts from a base that is missing it.
+
+## Release guidance
+
+```bash
+# 1. cut the release branch from development, commit the version bumps
+git checkout development
+git checkout -b release/vX.Y.Z
+git commit -am "Prepare vX.Y.Z"
+
+# 2. release branch -> development
+git checkout development
+git merge --no-ff release/vX.Y.Z -m "Merge release prep for vX.Y.Z"
+
+# 3. development -> main
+git checkout main
+git merge --no-ff development -m "Merge development for vX.Y.Z"
+
+# 4. tag the main merge commit, then push
+git tag vX.Y.Z
+git push origin development
+git push origin main
+git push origin vX.Y.Z
+```
+
+The tag belongs on the step-3 merge commit on `main`, not on the release branch and not
+on `development`. Pushing the tag is what triggers the wrapper publish workflows, which
+read the version from the tag.
+
+If the work is already on `main`, make a normal commit and tag that commit. Do not rewrite history just to avoid a merge commit.
+
+## Avoid
+
+- `git merge --ff`
+- `git pull --ff-only` as a default recommendation for this repo's merge policy
+- Tagging a branch tip that has not been merged into `main` when the intended release source of truth is `main`
+- Merging a release branch directly into `main`, skipping `development`
+
+## Why
+
+The repo wants explicit history. Release commits should be easy to find, easy to audit, and clearly connected to the branch that introduced them.

{onde_cli-0.3.1 → onde_cli-0.4.0}/.github/workflows/release-github.yml

@@ -190,3 +190,18 @@ jobs:
               }
             })
             console.log('Dispatched release-homebrew.yml for tag ${{ steps.tag.outputs.tag }}')
+
+      - name: Trigger pub.dev release
+        uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.actions.createWorkflowDispatch({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              workflow_id: 'release-pub.yml',
+              ref: 'main',
+              inputs: {
+                tag: '${{ steps.tag.outputs.tag }}'
+              }
+            })
+            console.log('Dispatched release-pub.yml for tag ${{ steps.tag.outputs.tag }}')

{onde_cli-0.3.1 → onde_cli-0.4.0}/.github/workflows/release-pub.yml

@@ -1,9 +1,6 @@
 name: pub.dev Release
 
 on:
-  push:
-    tags:
-      - "v*.*.*"
   workflow_dispatch:
     inputs:
       tag:
@@ -16,98 +13,11 @@ permissions:
 env:
   CARGO_TERM_COLOR: always
   PUB_PACKAGE_NAME: onde_cli
-  ONDE_APP_ID: ${{ secrets.ONDE_APP_ID }}
-  ONDE_APP_SECRET: ${{ secrets.ONDE_APP_SECRET }}
-  GRESIQ_API_KEY: ${{ secrets.GRESIQ_API_KEY }}
-  GRESIQ_API_SECRET: ${{ secrets.GRESIQ_API_SECRET }}
-  HF_TOKEN: ${{ secrets.HF_TOKEN }}
 
 jobs:
-  build-native-binaries:
-    name: Build native binary (${{ matrix.build.NAME }})
-    runs-on: ${{ matrix.build.OS }}
-    strategy:
-      fail-fast: false
-      matrix:
-        build:
-          - {
-              NAME: linux-x64,
-              OS: ubuntu-latest,
-              TARGET: x86_64-unknown-linux-gnu,
-            }
-          - {
-              NAME: linux-arm64,
-              OS: ubuntu-24.04-arm,
-              TARGET: aarch64-unknown-linux-gnu,
-            }
-          - {
-              NAME: windows-x64,
-              OS: windows-2022,
-              TARGET: x86_64-pc-windows-msvc,
-            }
-          - {
-              NAME: windows-arm64,
-              OS: windows-2022,
-              TARGET: aarch64-pc-windows-msvc,
-            }
-          - {
-              NAME: darwin-x64,
-              OS: macos-26-intel,
-              TARGET: x86_64-apple-darwin,
-            }
-          - { NAME: darwin-arm64, OS: macos-26, TARGET: aarch64-apple-darwin }
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6
-        with:
-          ref: ${{ github.event.inputs.tag || github.ref }}
-
-      - name: Read Rust toolchain
-        shell: bash
-        run: |
-          rust_toolchain="$(sed -n 's/^channel = "\(.*\)"/\1/p' rust-toolchain.toml | head -n 1)"
-          if [ -z "$rust_toolchain" ]; then
-            echo "Failed to read Rust toolchain from rust-toolchain.toml" >&2
-            exit 1
-          fi
-          echo "RUST_TOOLCHAIN=${rust_toolchain}" >> "$GITHUB_ENV"
-
-      - name: Install Rust toolchain
-        uses: dtolnay/rust-toolchain@3c5f7ea28cd621ae0bf5283f0e981fb97b8a7af9
-        with:
-          toolchain: ${{ env.RUST_TOOLCHAIN }}
-          targets: ${{ matrix.build.TARGET }}
-
-      - name: Setup Rust cache
-        uses: Swatinem/rust-cache@v2
-        with:
-          key: pub-${{ matrix.build.TARGET }}
-
-      - name: Build binary
-        shell: bash
-        run: cargo build --locked --release --target ${{ matrix.build.TARGET }}
-
-      - name: Prepare artifact
-        shell: bash
-        run: |
-          executable_name="onde"
-          if [[ "${{ matrix.build.OS }}" == "windows-2022" ]]; then
-            executable_name="onde.exe"
-          fi
-
-          mkdir -p "pub-artifacts/native/${{ matrix.build.NAME }}"
-          cp "target/${{ matrix.build.TARGET }}/release/${executable_name}" "pub-artifacts/native/${{ matrix.build.NAME }}/${executable_name}"
-
-      - name: Upload native artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: pub-native-${{ matrix.build.NAME }}
-          path: pub-artifacts/native
-
   verify-package:
     name: Verify Dart package
     runs-on: ubuntu-latest
-    needs: build-native-binaries
     steps:
       - name: Checkout
         uses: actions/checkout@v6
@@ -125,17 +35,6 @@ jobs:
           fi
           echo "RELEASE_VERSION=${release_version}" >> "$GITHUB_ENV"
 
-      - name: Download native artifacts
-        uses: actions/download-artifact@v4
-        with:
-          pattern: pub-native-*
-          path: pub/onde_cli/native
-          merge-multiple: true
-
-      - name: Stage generated native binaries
-        shell: bash
-        run: git add -f pub/onde_cli/native
-
       - name: Setup Dart SDK
         uses: dart-lang/setup-dart@v1
 
@@ -187,17 +86,6 @@ jobs:
           fi
           echo "RELEASE_VERSION=${release_version}" >> "$GITHUB_ENV"
 
-      - name: Download native artifacts
-        uses: actions/download-artifact@v4
-        with:
-          pattern: pub-native-*
-          path: pub/onde_cli/native
-          merge-multiple: true
-
-      - name: Stage generated native binaries
-        shell: bash
-        run: git add -f pub/onde_cli/native
-
       - name: Setup Dart SDK
         uses: dart-lang/setup-dart@v1
 

onde_cli-0.4.0/AGENTS.md

@@ -0,0 +1,69 @@
+# AGENTS.md
+
+`onde-cli` is a Rust TUI (`onde` binary) for managing an Onde Inference account and running a local model pipeline: LoRA fine-tune → adapter merge → GGUF export → local chat test → Hugging Face upload → model assignment to an Onde app. npm, PyPI, NuGet, pub.dev, Homebrew, and crates.io are thin wrappers around this one binary; the Rust crate is the source of truth.
+
+## Build, test, lint
+
+```sh
+cargo build                  # debug build
+cargo run                    # launch the TUI
+cargo run -- --mcp           # run as an MCP server over stdio (no TUI)
+cargo test --locked          # unit tests (heavy ones are #[ignore])
+cargo clippy --all-targets -- -D warnings
+cargo fmt -- --check
+```
+
+The build **requires** these env vars (read from `.env` via `build.rs`): `ONDE_APP_ID`, `ONDE_APP_SECRET`, `GRESIQ_API_KEY`, `GRESIQ_API_SECRET`. `HF_TOKEN` is optional. They are baked in at compile time via `env!(...)` in `src/app.rs`. Changing `.env` triggers a full rebuild.
+
+On macOS, candle's `metal` + `accelerate` features are added automatically. **Fine-tuning always runs on CPU** — Metal's backward pass in candle 0.10.2 produces corrupt gradients (1e6–1e29 in magnitude, where CPU gives ~40–65 for identical losses). Use `ONDE_FINETUNE_METAL=1` only to test newer candle versions, and verify with `ONDE_FINETUNE_GRAD_DEBUG=1` (per-step loss/max_abs/norm).
+
+Linux CI requires `libclang-dev` (`sudo apt-get install -y libclang-dev`).
+
+### Tests that load real models
+
+`src/gguf.rs` has two `#[ignore]` integration tests that export a ~1GB GGUF and run inference through `onde::mistralrs`. They need a Qwen3-0.6B model cached in the Onde App Group container and skip gracefully when it is absent.
+
+```sh
+cargo test gguf::tests::exported_qwen3_gguf_is_runnable -- --ignored --nocapture
+cargo test gguf::tests::finetune_merge_export_run     -- --ignored --nocapture
+```
+
+Env knobs for these: `ONDE_TEST_MODEL_DIR`, `ONDE_TEST_DTYPE` (`f16`/`q8_0`), `ONDE_TEST_LR`, `ONDE_TEST_DATA_PATH`, `ONDE_TEST_EPOCHS`, `ONDE_TEST_MAX_SEQ_LEN`, `ONDE_TEST_EVAL_PROMPT` (`||`-separated prompts), `ONDE_TEST_SYSTEM_PROMPT`. This makes the full-pipeline test double as a headless fine-tune runner for a custom dataset.
+
+### Debugging the TUI
+
+`main.rs` redirects both stdout and stderr to `~/.cache/onde/debug.log` before ratatui takes the alternate screen, because `mistral.rs` writes to both fds and would otherwise tear up the display. To see what the app or the inference engine is doing, tail that log; `println!`/`eprintln!`/`log::*` all land there, not on screen.
+
+## Architecture — `src/`
+
+| File(s) | Responsibility |
+|---|---|
+| `main.rs` | Entry point; redirects stdout/stderr to `~/.cache/onde/debug.log` before ratatui takes over |
+| `app.rs` | `App` struct + `Screen` state machine + `AuthEvent` channel (`tokio::select!` over an `mpsc` channel and a `crossterm` `EventStream`); `App::apply` folds background progress into state |
+| `ui.rs` | Pure ratatui render of `App`; no SDK imports (re-exports types through `app.rs`) |
+| `finetune.rs` | Hand-written LoRA trainer (candle, CPU): Qwen forward pass (RMSNorm, RoPE, GQA, optional Qwen3 QK-norm), LoRA A/B trained on q/v projections in F32, writes `lora_adapter.safetensors`. Gradients are sanitized (non-finite elements zeroed) and globally norm-clipped in a scaled space before each AdamW step; a step is skipped (loudly) only when the norm is zero or non-finite. **Skipping this guard corrupts every weight after the first bad step.** |
+| `merge.rs` | Folds LoRA adapter into base weights (`W + scale·(B@A)`); writes `model.safetensors` plus copied config/tokenizer |
+| `gguf.rs` | Hand-rolled GGUF writer (no llama.cpp). Tensor dims are written innermost-first — reverse of safetensors shape, because candle reverses on read; `head_dim` comes from config and is emitted as `attention.key_length`/`value_length` (Qwen3 decouples it from `hidden_size/num_heads`); `token_type` is an INT32 array; `general.architecture` is chosen from `model_type` so Qwen3 routes to candle's `quantized_qwen3` loader |
+| `chat.rs` | Local GGUF chat via `onde::mistralrs::GgufModelBuilder`, the same engine the Onde SDK uses, so a model can be tested before publishing |
+| `hf_upload.rs` / `hf_clone.rs` / `hf_search.rs` / `hf.rs` | Hugging Face Hub: upload the GGUF, check/create a repo, search models, and resolve/merge the local HF cache (incl. the macOS Onde App Group container) |
+| `gresiq.rs` | `smbcloud-gresiq-sdk` wrapper for apps and the model catalog. "Deploying" a model means `assign_model(app_id, model_id)` against a catalog entry; the end app then fetches that assignment through the Onde SDK's `load_assigned_model` and downloads the GGUF. The CLI can only assign models that already exist in the GresIQ catalog |
+| `token.rs` | Auth token persistence |
+| `project.rs` | Per-project fine-tune workspaces under `~/.onde` |
+
+**Background task rule:** network/IO → `tokio::spawn`; CPU-heavy tensor work (`finetune`, `merge`, `gguf`) → `std::thread::spawn` to avoid starving the async runtime.
+
+**Adding a feature pattern:** new `Screen` variant → key handler → `AuthEvent` variant → background task that streams progress events.
+
+### The `onde` dependency
+
+The `onde` crate provides the inference engine (`onde::mistralrs`, a vendored mistral.rs) and `onde::inference::models::SUPPORTED_MODEL_INFO` (the supported-model catalog the inference picker mirrors). It is normally the published crate; `Cargo.toml` has commented `path`/`[patch.crates-io]` blocks for developing against local checkouts of `onde`, the `smbcloud-*` crates, and `candle` — never commit with those uncommented.
+
+## Conventions
+
+- **Git:** merge feature/release/hotfix branches with `--no-ff`. Tag the merge commit on `main`. Never tag a branch tip that hasn't been merged. See `.agents/skills/git/SKILL.md`.
+- **Commits:** include `Co-Authored-By: siGit Code <297239231+sigitc@users.noreply.github.com>` trailer when committing with the agent.
+- **`[patch.crates-io]` and `path =` deps:** commented out in `Cargo.toml` for local dev against `onde`/`smbcloud-*`/`candle`. Never commit with these uncommented.
+- **Distribution:** before touching any wrapper package (npm, PyPI, NuGet, pub.dev, Homebrew), read `.agents/skills/distribution/SKILL.md`. Keep all channel versions aligned with the Rust crate version in `Cargo.toml`.
+- **Wrapper packages** are in `npm/`, `pypi/`, `nuget/`, `pub/`. The npm base manifest is rewritten at release time by `npm/scripts/render-main-package.cjs`; do not hand-edit committed package.json versions as the source of truth for releases.
+- **Clippy** runs with `-D warnings` in CI; all lints must pass.
+- **Rust edition:** 2024; toolchain: stable.

onde_cli-0.4.0/CLAUDE.md

@@ -0,0 +1,69 @@
+# AGENTS.md
+
+`onde-cli` is a Rust TUI (`onde` binary) for managing an Onde Inference account and running a local model pipeline: LoRA fine-tune → adapter merge → GGUF export → local chat test → Hugging Face upload → model assignment to an Onde app. npm, PyPI, NuGet, pub.dev, Homebrew, and crates.io are thin wrappers around this one binary; the Rust crate is the source of truth.
+
+## Build, test, lint
+
+```sh
+cargo build                  # debug build
+cargo run                    # launch the TUI
+cargo run -- --mcp           # run as an MCP server over stdio (no TUI)
+cargo test --locked          # unit tests (heavy ones are #[ignore])
+cargo clippy --all-targets -- -D warnings
+cargo fmt -- --check
+```
+
+The build **requires** these env vars (read from `.env` via `build.rs`): `ONDE_APP_ID`, `ONDE_APP_SECRET`, `GRESIQ_API_KEY`, `GRESIQ_API_SECRET`. `HF_TOKEN` is optional. They are baked in at compile time via `env!(...)` in `src/app.rs`. Changing `.env` triggers a full rebuild.
+
+On macOS, candle's `metal` + `accelerate` features are added automatically. **Fine-tuning always runs on CPU** — Metal's backward pass in candle 0.10.2 produces corrupt gradients (1e6–1e29 in magnitude, where CPU gives ~40–65 for identical losses). Use `ONDE_FINETUNE_METAL=1` only to test newer candle versions, and verify with `ONDE_FINETUNE_GRAD_DEBUG=1` (per-step loss/max_abs/norm).
+
+Linux CI requires `libclang-dev` (`sudo apt-get install -y libclang-dev`).
+
+### Tests that load real models
+
+`src/gguf.rs` has two `#[ignore]` integration tests that export a ~1GB GGUF and run inference through `onde::mistralrs`. They need a Qwen3-0.6B model cached in the Onde App Group container and skip gracefully when it is absent.
+
+```sh
+cargo test gguf::tests::exported_qwen3_gguf_is_runnable -- --ignored --nocapture
+cargo test gguf::tests::finetune_merge_export_run     -- --ignored --nocapture
+```
+
+Env knobs for these: `ONDE_TEST_MODEL_DIR`, `ONDE_TEST_DTYPE` (`f16`/`q8_0`), `ONDE_TEST_LR`, `ONDE_TEST_DATA_PATH`, `ONDE_TEST_EPOCHS`, `ONDE_TEST_MAX_SEQ_LEN`, `ONDE_TEST_EVAL_PROMPT` (`||`-separated prompts), `ONDE_TEST_SYSTEM_PROMPT`. This makes the full-pipeline test double as a headless fine-tune runner for a custom dataset.
+
+### Debugging the TUI
+
+`main.rs` redirects both stdout and stderr to `~/.cache/onde/debug.log` before ratatui takes the alternate screen, because `mistral.rs` writes to both fds and would otherwise tear up the display. To see what the app or the inference engine is doing, tail that log; `println!`/`eprintln!`/`log::*` all land there, not on screen.
+
+## Architecture — `src/`
+
+| File(s) | Responsibility |
+|---|---|
+| `main.rs` | Entry point; redirects stdout/stderr to `~/.cache/onde/debug.log` before ratatui takes over |
+| `app.rs` | `App` struct + `Screen` state machine + `AuthEvent` channel (`tokio::select!` over an `mpsc` channel and a `crossterm` `EventStream`); `App::apply` folds background progress into state |
+| `ui.rs` | Pure ratatui render of `App`; no SDK imports (re-exports types through `app.rs`) |
+| `finetune.rs` | Hand-written LoRA trainer (candle, CPU): Qwen forward pass (RMSNorm, RoPE, GQA, optional Qwen3 QK-norm), LoRA A/B trained on q/v projections in F32, writes `lora_adapter.safetensors`. Gradients are sanitized (non-finite elements zeroed) and globally norm-clipped in a scaled space before each AdamW step; a step is skipped (loudly) only when the norm is zero or non-finite. **Skipping this guard corrupts every weight after the first bad step.** |
+| `merge.rs` | Folds LoRA adapter into base weights (`W + scale·(B@A)`); writes `model.safetensors` plus copied config/tokenizer |
+| `gguf.rs` | Hand-rolled GGUF writer (no llama.cpp). Tensor dims are written innermost-first — reverse of safetensors shape, because candle reverses on read; `head_dim` comes from config and is emitted as `attention.key_length`/`value_length` (Qwen3 decouples it from `hidden_size/num_heads`); `token_type` is an INT32 array; `general.architecture` is chosen from `model_type` so Qwen3 routes to candle's `quantized_qwen3` loader |
+| `chat.rs` | Local GGUF chat via `onde::mistralrs::GgufModelBuilder`, the same engine the Onde SDK uses, so a model can be tested before publishing |
+| `hf_upload.rs` / `hf_clone.rs` / `hf_search.rs` / `hf.rs` | Hugging Face Hub: upload the GGUF, check/create a repo, search models, and resolve/merge the local HF cache (incl. the macOS Onde App Group container) |
+| `gresiq.rs` | `smbcloud-gresiq-sdk` wrapper for apps and the model catalog. "Deploying" a model means `assign_model(app_id, model_id)` against a catalog entry; the end app then fetches that assignment through the Onde SDK's `load_assigned_model` and downloads the GGUF. The CLI can only assign models that already exist in the GresIQ catalog |
+| `token.rs` | Auth token persistence |
+| `project.rs` | Per-project fine-tune workspaces under `~/.onde` |
+
+**Background task rule:** network/IO → `tokio::spawn`; CPU-heavy tensor work (`finetune`, `merge`, `gguf`) → `std::thread::spawn` to avoid starving the async runtime.
+
+**Adding a feature pattern:** new `Screen` variant → key handler → `AuthEvent` variant → background task that streams progress events.
+
+### The `onde` dependency
+
+The `onde` crate provides the inference engine (`onde::mistralrs`, a vendored mistral.rs) and `onde::inference::models::SUPPORTED_MODEL_INFO` (the supported-model catalog the inference picker mirrors). It is normally the published crate; `Cargo.toml` has commented `path`/`[patch.crates-io]` blocks for developing against local checkouts of `onde`, the `smbcloud-*` crates, and `candle` — never commit with those uncommented.
+
+## Conventions
+
+- **Git:** merge feature/release/hotfix branches with `--no-ff`. Tag the merge commit on `main`. Never tag a branch tip that hasn't been merged. See `.agents/skills/git/SKILL.md`.
+- **Commits:** include `Co-Authored-By: siGit Code <297239231+sigitc@users.noreply.github.com>` trailer when committing with the agent.
+- **`[patch.crates-io]` and `path =` deps:** commented out in `Cargo.toml` for local dev against `onde`/`smbcloud-*`/`candle`. Never commit with these uncommented.
+- **Distribution:** before touching any wrapper package (npm, PyPI, NuGet, pub.dev, Homebrew), read `.agents/skills/distribution/SKILL.md`. Keep all channel versions aligned with the Rust crate version in `Cargo.toml`.
+- **Wrapper packages** are in `npm/`, `pypi/`, `nuget/`, `pub/`. The npm base manifest is rewritten at release time by `npm/scripts/render-main-package.cjs`; do not hand-edit committed package.json versions as the source of truth for releases.
+- **Clippy** runs with `-D warnings` in CI; all lints must pass.
+- **Rust edition:** 2024; toolchain: stable.