Add AGENTS.md with build, architecture, and convention guidance
Co-Authored-By: siGit Code <297239231+sigitc@users.noreply.github.com>
keypair34 committed
Jul 12, 2026 at 07:45 UTC
a8c9e18a21d7bfd30335b47bea2eb0e319d540e7
1 file changed
+49
AGENTS.md
new
+49
@@ -0,0 +1,49 @@
1
+# AGENTS.md
2
+
3
+`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.
4
+
5
+## Build, test, lint
6
+
7
+```sh
8
+cargo build # debug build
9
+cargo run # launch the TUI
10
+cargo test --locked # unit tests (heavy ones are #[ignore])
11
+cargo clippy --all-targets -- -D warnings
12
+cargo fmt -- --check
13
+```
14
+
15
+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.
16
+
17
+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. Use `ONDE_FINETUNE_METAL=1` only to test newer candle versions, and verify with `ONDE_FINETUNE_GRAD_DEBUG=1`.
18
+
19
+Linux CI requires `libclang-dev` (`sudo apt-get install -y libclang-dev`).
20
+
21
+## Architecture — `src/`
22
+
23
+| File(s) | Responsibility |
24
+|---|---|
25
+| `main.rs` | Entry point; redirects stdout/stderr to `~/.cache/onde/debug.log` before ratatui takes over |
26
+| `app.rs` | `App` struct + `Screen` state machine + `AuthEvent` channel; `App::apply` folds background progress into state |
27
+| `ui.rs` | Pure ratatui render of `App`; no SDK imports (re-exports types through `app.rs`) |
28
+| `finetune.rs` | Hand-written LoRA trainer (candle, CPU). Writes `lora_adapter.safetensors` |
29
+| `merge.rs` | Folds LoRA adapter into base weights; writes `model.safetensors` |
30
+| `gguf.rs` | Hand-rolled GGUF writer (no llama.cpp). Tensor dims innermost-first; `head_dim` → `attention.key_length/value_length` |
31
+| `chat.rs` | Local GGUF chat via `onde::mistralrs::GgufModelBuilder` |
32
+| `hf*.rs` | Hugging Face Hub: upload, clone, search, cache resolution |
33
+| `gresiq.rs` | `smbcloud-gresiq-sdk` wrapper; model assignment (`assign_model`) |
34
+| `token.rs` | Auth token persistence |
35
+| `project.rs` | Per-project fine-tune workspaces under `~/.onde` |
36
+
37
+**Background task rule:** network/IO → `tokio::spawn`; CPU-heavy tensor work (`finetune`, `merge`, `gguf`) → `std::thread::spawn` to avoid starving the async runtime.
38
+
39
+**Adding a feature pattern:** new `Screen` variant → key handler → `AuthEvent` variant → background task that streams progress events.
40
+
41
+## Conventions
42
+
43
+- **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`.
44
+- **Commits:** include `Co-Authored-By: siGit Code <297239231+sigitc@users.noreply.github.com>` trailer when committing with the agent.
45
+- **`[patch.crates-io]` and `path =` deps:** commented out in `Cargo.toml` for local dev against `onde`/`smbcloud-*`/`candle`. Never commit with these uncommented.
46
+- **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`.
47
+- **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.
48
+- **Clippy** runs with `-D warnings` in CI; all lints must pass.
49
+- **Rust edition:** 2024; toolchain: stable.