@sigitcodereview / sigit
Code Commits Issues Pulls Cloud Agent CI/CD
claude/linked-issue-acp-tui-u4vvpa
claude/github-issue-40-0au5ua claude/linked-issue-acp-tui-u4vvpa claude/minor-release-cut-vkugow claude/sigit-acp-local-chat-cx6380 claude/sigit-cloud-agent-expansion-reox0a claude/tool-permission-system claude/zen-feynman-0u78dk development feature/acp-cancel-request feature/acp-session-list-cursor feature/acp-v1-conformance feature/agent-tools-multiedit-glob-todos-remember feature/cargo-workspace feature/hooks feature/load-local-model-explicitly feature/sigit-agent-profile feature/sigit-code-cloud feature/xcode-mcp-server fix/acp-replay-loaded-session-history fix/acp-replay-reasoning-and-attachments fix/dsml-doubled-bar-markers main release/v1.5.10 release/v1.5.6 release/v1.6.1
md 397 lines 28.2 KB
Rendered Raw
1 # AGENTS.md
2
3 This file provides guidance to AI coding agents when working with code in this repository.
4
5 ## What this is
6
7 `sigit` ("siGit Code") is a single Rust binary: a local-first AI coding agent that runs LLM
8 inference on-device (via the `onde` crate / GGUF models) or against a hosted/OpenAI-compatible
9 endpoint. It exposes itself two ways from the *same* binary, chosen at startup by whether stdin
10 is a TTY:
11
12 - **ACP mode** (stdin not a TTY): speaks the Agent Client Protocol over stdio for editor
13 integration (Zed, VS Code ACP Client). Cross-platform.
14 - **Interactive terminal mode** (stdin is a TTY): a full-screen ratatui chat UI. **Unix-only** —
15 it relies on fd redirection to keep logs out of the TUI, so Windows gets ACP mode only.
16
17 Before the TTY/ACP split, `main` also dispatches the account subcommands `sigit login`,
18 `sigit logout`, `sigit whoami` (see `src/main.rs` `main()`).
19
20 ## Working in this repo
21
22 **IMPORTANT — branch naming:** Prefix every working branch with `feature/` (new functionality)
23 or `fix/` (bug fixes) — never a tool- or agent-name prefix like `claude/`. Name the branch after
24 the *changes it contains*, as a short, descriptive, kebab-case slug that is self-explanatory
25 from the name alone (e.g. `feature/tool-permission-system`, `fix/glob-mtime-sort`), never after
26 a task, ticket, or session id (not `feature/task-q003hm`).
27
28 **IMPORTANT — pull request target:** Always open pull requests against the `development` branch,
29 never `main`. `main` is release-only; `development` is where day-to-day work integrates, and the
30 release merge (see the `sigit-code-release` skill) is the one thing that ever puts commits on
31 `main`.
32
33 This rule needs help to hold, because the repository's default branch is `main`: both
34 `gh pr create` and the GitHub web form pre-select it, so a PR lands on the wrong base unless the
35 base is passed explicitly. Pass it every time, and check that it took:
36
37 ```sh
38 gh pr create --base development --head <branch>
39 gh pr view <number> --json baseRefName
40 ```
41
42 Retargeting a PR that was opened against `main` costs nothing before it merges:
43 `gh pr edit <number> --base development`. After it merges it costs real work — the change sits on
44 `main` while `development`, which the next release is cut from, does not have it, and someone has
45 to carry it back by hand. PR #65 went in that way.
46
47 **IMPORTANT — branch off `development`:** Start every working branch from the latest
48 `origin/development`. Exception: when new work *depends on* a feature branch that has not merged
49 yet (e.g. it builds on tools or APIs that branch introduces), it may be stacked on top of that
50 branch instead. When stacking: merge the base PR into `development` first, then rebase the
51 stacked branch onto `development` before opening its pull request, so each PR shows only its own
52 commits.
53
54 **IMPORTANT — run CI before pushing:** Run the full CI gate locally and confirm it is green
55 *before* pushing a branch or opening a pull request — never push work that fails these:
56
57 ```sh
58 cargo fmt -- --check # formatting
59 cargo clippy --tests -- -D warnings # lint (warnings are errors)
60 cargo test --locked # tests
61 ```
62
63 ## Agent assets layout
64
65 `.agents/` is the canonical home for agent assets; every other agent path in
66 the repo is a symlink into it, never a copy:
67
68 - `.agents/AGENTS.md` — this file, the project instructions. The root
69 `AGENTS.md` and `CLAUDE.md` are symlinks to it, so agents.md-standard tools,
70 Claude Code, and sigit itself (via `src/instructions.rs`, which prefers
71 `AGENTS.md` over `CLAUDE.md` in the same directory and therefore reads it
72 once) all load the same content. Edit this file; never replace the root
73 symlinks with real files.
74 - `.agents/skills/` — all project skills. `.claude/skills` is a symlink to it,
75 which is how both Claude Code and sigit itself (via `src/skills.rs`) discover
76 them. Add new skills under `.agents/skills/<name>/SKILL.md`, never as real
77 files under `.claude/`.
78
79 ## Build / test / lint
80
81 ```sh
82 cargo build # debug build
83 cargo build --release # release binary at target/release/sigit
84 cargo run # launches interactive TUI (stdin is a TTY)
85 cargo test # CI runs: cargo test --locked --target <target>
86 cargo clippy --tests -- -D warnings # CI gate: clippy is -D warnings on all 4 targets
87 cargo fmt -- --check # CI gate (edition 2024)
88 ```
89
90 CI (`.github/workflows/ci.yml`) runs fmt + clippy + test across four targets:
91 `aarch64-apple-darwin`, `x86_64-apple-darwin`, `x86_64-unknown-linux-gnu`,
92 `x86_64-pc-windows-msvc`. Clippy is `-D warnings`, so warnings fail the build.
93
94 Run a single test: `cargo test <test_name>`.
95
96 ## Critical platform constraint: `#[cfg(unix)]` dead code
97
98 The interactive client is `#[cfg(unix)]`-only. The `InferenceBackend` seam (`backend.rs`) and
99 provider resolution (`provider.rs`) are consumed by both the interactive client and the ACP
100 server, but several of their items are reached only through the Unix-only interactive paths, so
101 the dead-code lint is suppressed *on non-Unix targets only*.
102
103 Consequence: code can pass clippy on macOS/Linux but fail on the Windows target (or vice versa).
104 When touching `backend.rs`, `provider.rs`, or the interactive path, keep the `cfg` gates intact —
105 don't "fix" an unused-warning by deleting code that's live on Unix.
106
107 ## Architecture
108
109 The agent loop is backend-agnostic. The flow: a turn (messages + tool specs) goes to an
110 `InferenceBackend`, which returns assistant text and/or tool calls; the loop executes tools and
111 feeds results back. Neither the loop nor ACP/TUI surfaces depend on a concrete backend.
112
113 - **`src/main.rs`** — entry point, mode dispatch, the full ACP `Agent` impl (session lifecycle:
114 new/load/fork/prompt/cancel, config options, slash-command advertisement), and the `SYSTEM_PROMPT`.
115 ACP session state owns its roots, conversation, and selected model even though the process has
116 one live backend; activating a thread parks and restores all three. Unknown session ids are
117 rejected instead of silently borrowing the active thread's cwd. Prompt cancellation is routed
118 outside `turn_lock`, which lets a client cancel the turn currently holding that lock. The
119 `SYSTEM_PROMPT` bakes in smbCloud-specific context the agent should use when the repo is clearly
120 smbCloud, and stay general otherwise.
121 - **`src/backend.rs`** — the `InferenceBackend` trait and neutral types (`ToolSpec`, `ToolCall`,
122 `ToolResult`, `TurnResult`). Two impls: `LocalBackend` (on-device via `onde::ChatEngine`) and
123 `OpenAiBackend` (any OpenAI-compatible HTTP endpoint). A `BackendError` is user-facing: the
124 ACP prompt handler passes it to the client verbatim and the editor puts it in an error banner,
125 so `describe_api_error` unwraps the OpenAI `{"error":{"message":…}}` envelope and shows that
126 message on its own, falling back to the status only when there is nothing to unwrap. An
127 endpoint can also fail *after* the response is open, reporting it as a `data:` frame holding
128 the same envelope; that frame has no `choices`, so `consume_stream` has to check for it
129 explicitly or it parses as an empty chunk and the turn ends looking like an empty answer.
130 Some models write tool calls into content as text; `src/inline_tool_calls.rs` recovers the
131 well-formed ones. A block that doesn't parse (or never closes) is dropped from both the reply
132 and history, and `OpenAiBackend::complete` retries once with a note telling the model the call
133 didn't run. Leaving the raw block in history makes the model invent `<function_results>` later.
134 - **`src/provider.rs`** — decides *which* backend serves inference. Resolution order, first match
135 wins: (1) override via `OPENAI_BASE_URL`+`OPENAI_API_KEY` or active profile in
136 `~/.config/sigit/providers.toml`; (2) siGit Code Cloud when logged in; (3) on-device.
137 - **`src/tools.rs`** — agent tool schemas + execution: `read_file`, `create_directory`,
138 `list_directory`, `search_files`, `glob`, `read_website`, `create_file`, `edit_file`,
139 `multi_edit`, `delete_file`, `run_command`, `write_todos`, `remember`. Add a tool in both the
140 spec list (`all_tools`) and the execute `match` (`execute_tool`). `run_command` also enforces
141 commit attribution: when a command creates a new commit that lacks the
142 `Co-Authored-By: siGit Code` trailer (`commit_co_author_trailer()`, which reads
143 `siGit Code v<version>-<acp|tui|headless>` from the surface `main` sets via `set_surface`), it amends the trailer in —
144 unless the commit already exists on a remote, which is never rewritten. Every child process it
145 spawns (`spawn_shell`, the `git` helpers, and `hooks.rs`) sets `stdin` to null and never
146 inherits it: in ACP mode sigit's stdin is the JSON-RPC pipe from the editor, so a command that
147 reads stdin both blocks forever and eats the client's next request, wedging the session past
148 any timeout. On Unix the shell also leads its own process group so the timeout kills the whole
149 tree, and stdout/stderr are drained on threads while the command runs — waiting first and
150 reading after deadlocks as soon as the output outgrows the pipe buffer. Also owns the `task`
151 tool: a nested agent loop in a fresh conversation, offered only when `subagent_available()`
152 (a subagent factory is registered — see `register_subagent_factory_for` in `main.rs`; on-device
153 registers a `None`-returning factory since onde has a single shared history). A subagent's
154 toolset is a hard-gated read-only allow-list (`SUBAGENT_TOOL_NAMES`) that is never expanded by a
155 configurable subagent type (see `src/subagents.rs`) — only ever narrowed — so a `.sigit/agents/*.md`
156 file can't grant itself `edit_file`/`run_command` and bypass the permission system. Also owns
157 `web_search`: a thin native wrapper around the official MCP server's Brave-Search-backed
158 `web_search` tool (`mcp__sigit__web_search`, implemented server-side in `sigit-si`'s
159 `WebSearchService` + `Mcp::Tools::WebSearch`), offered only when that MCP tool was actually
160 discovered (i.e. the user is signed in to siGit Code Cloud — see `web_search_available`).
161 Wrapping it natively rather than leaving it as a raw `mcp__*` tool matters for two reasons:
162 `permissions::classify` treats every `mcp__*` tool as mutating (an "ask" prompt on every call),
163 while `web_search` is read-only like `read_website`; and the raw delegate name is filtered out
164 of the assembled tool list (`is_web_search_delegate`) so the model sees one clean option, not
165 two names for the same tool. Execution still forwards verbatim to `mcp::call_tool` — no second
166 HTTP/JSON-RPC implementation.
167 - **`src/skills.rs`** — [Agent Skills](https://agentskills.io) support. Discovers skill
168 folders (each with a `SKILL.md`: YAML frontmatter `name` + `description`, then Markdown
169 instructions) from `.sigit/skills/` and `.claude/skills/` in every project root (see `src/workspace.rs`),
170 `$SIGIT_CONFIG_DIR/skills/`,
171 and `~/.claude/skills/`. Progressive disclosure: the discovery list (name + description) is
172 baked into the dynamically-built `skill` tool's description, and activating a skill (the model
173 calls `skill` with a name) loads the full `SKILL.md` body. The `skill` tool is appended in the
174 `*_as_specs`/`build_tool_specs` layer (not in `all_tools()`) so its description can be dynamic,
175 and only when at least one skill exists.
176 - **`src/commands.rs`** — user-defined slash commands. Discovers Markdown files (each an
177 optional YAML frontmatter block — `description`, `argument-hint` — followed by a prompt-template
178 body) from `.sigit/commands/` and `.claude/commands/` in every project root, `$SIGIT_CONFIG_DIR/commands/`,
179 and `~/.claude/commands/`. A subdirectory namespaces the command with `:`
180 (`.sigit/commands/git/commit.md` → `/git:commit`). Unlike skills there's no tool-call
181 indirection: invoking one works exactly like the built-in `/init` — `commands::render`
182 substitutes `$ARGUMENTS`/`$1..$9` in the body against whatever followed the command on the
183 input line, and the result is fed to the model as a normal turn through the ordinary tools and
184 permission checks. Resolution happens where each surface (`main.rs`/`chat.rs`) already
185 special-cases `/init`: an unrecognized slash command is tried against `commands::resolve_command`
186 before falling back to "unknown command". A custom command sharing a name with a built-in is
187 unreachable (built-ins match first in `parse_slash`) and is skipped when advertised to ACP
188 clients, with a warning logged.
189 - **`src/subagents.rs`** — configurable subagent types for the `task` tool. Discovers Markdown
190 files (YAML frontmatter `name` + `description`, optional comma-separated `tools:` allow-list,
191 then a Markdown body that becomes the subagent's system prompt) from `.sigit/agents/` and
192 `.claude/agents/` in every project root, `$SIGIT_CONFIG_DIR/agents/`, and `~/.claude/agents/`. Passing a
193 type's `name` as `task`'s `subagent_type` argument swaps in that system prompt and, if `tools:`
194 is set, narrows the offered toolset to its *intersection* with `SUBAGENT_TOOL_NAMES` — the
195 security-relevant narrowing logic lives in `tools.rs` next to that constant, not here; this
196 module only discovers and parses files. `SubagentFactory` (in `tools.rs`) takes the resolved
197 system prompt per call rather than baking one in at registration, so a single registered
198 factory serves both the default research subagent and every configured type.
199 - **`src/frontmatter.rs`** — shared "YAML frontmatter + Markdown body" parsing used by both
200 `src/skills.rs` (`SKILL.md`) and `src/commands.rs` (`.sigit/commands/*.md`).
201 - **`src/mcp.rs`** — [Model Context Protocol](https://modelcontextprotocol.io) *client*. Two
202 transports: **Streamable HTTP** (one JSON-RPC POST endpoint, `url` in `mcp.toml`; replies are
203 `application/json` or SSE) and **stdio** (`command` + optional `args`/`[server.env]` in
204 `mcp.toml`; sigit spawns the server and speaks newline-delimited JSON-RPC over its
205 stdin/stdout, stderr inherited into sigit's log). `url` and `command` are mutually exclusive —
206 both or neither is a config error, logged and skipped. Both transports run the same
207 `initialize`/`tools/list` handshake and forward `tools/call`. Discovery is best-effort at
208 startup (`mcp::init`, called from both branches of `main()`) and cached in a process-global so
209 the synchronous spec builders (`mcp::tool_specs`) and the async dispatch (`mcp::call_tool`) can
210 both read it; `/reload` does *not* re-run it, so config changes need a restart. stdio children
211 live for the process; a dead child fails calls with an in-band error string (no auto-restart).
212 Tools are namespaced `mcp__<server>__<tool>`, appended in the `*_as_specs`/`build_tool_specs`
213 layer and routed in `tools::execute_tool` via `mcp::is_mcp_tool`. Two servers are baked in:
214 the official server (`<cloud>/mcp`, default `https://sigit.si/api/v1/mcp`, always HTTP, authed
215 with the cloud session token) and the smbCloud CLI server (`smb --mcp`, stdio, added only when
216 the `smb` binary is on `PATH`; opt out with `smbcloud = false` in `mcp.toml` or
217 `SIGIT_MCP_SMBCLOUD=off`). A user-defined entry named `sigit` or `smbcloud` overrides the
218 corresponding baked-in one. Extra servers live in `mcp.toml` (global
219 `$SIGIT_CONFIG_DIR/mcp.toml` and project-local `.sigit/mcp.toml`). The stdio path is covered by
220 `tests/mcp_stdio.rs`, driven by the test-only `src/bin/mcp_stdio_stub.rs` helper binary
221 (excluded from the published crate via `exclude` in `Cargo.toml`). The baked-in official
222 server is *also* listed in the public MCP Registry as `si.sigit/sigit` — a **remote**
223 Streamable-HTTP listing owned by the [`getsigit/si`](https://github.com/getsigit/si) repo
224 (`server.json` at its root, published by its `release-mcp-registry.yml`), not this one. Because
225 it's a remote server, the registry's URL-match rule forces a domain namespace (`si.sigit` ↔
226 `sigit.si`) verified by a DNS TXT record, not the GitHub-OIDC scheme `smbcloud-cli` uses for its
227 package listing.
228 - **`src/permissions.rs`** — tool permission policy. Every tool call passes through
229 `decision_for` before executing: read-only tools always run; mutating tools (and all
230 `mcp__*`/unknown tools) are governed by, in order: per-session plan mode (`/plan` — deny all
231 mutating tools with a present-a-plan message), session "always allow" grants, per-tool
232 overrides and the default mode from `[permissions]` in `settings.toml` (`allow`/`ask`/`deny`,
233 default `ask`; `SIGIT_PERMISSIONS` env overrides the default). On `ask`, the ACP path sends
234 `session/request_permission` (allow once / allow for session / deny) and the TUI pauses the
235 inference task on a y/a/n prompt. Note: ACP turn-affecting handlers run in `cx.spawn`ed tasks
236 serialized by `SiGitAgent::turn_lock` so the dispatch loop can route the client's permission
237 answer mid-turn — don't move them back inline, and don't await client requests from inline
238 handlers (deadlock).
239 - **`src/instructions.rs`** — project instruction files, the always-on counterpart to skills.
240 Reads `AGENTS.md` (the cross-tool [agents.md](https://agents.md) standard) and `CLAUDE.md`,
241 walking from the session cwd up to the repo root (nearest ancestor with `.git`, never above it),
242 plus a global file under `$SIGIT_CONFIG_DIR`. Files are ordered outermost-first so the deepest
243 (most specific) wins. In a multi-root project that walk is repeated for every root
244 (`load_workspace_instructions`). The combined block is injected via `session_context_message`
245 in `main.rs` — pushed as a system message at every ACP session entry point (new/load/fork +
246 model switch) and appended to the system prompt on the cloud and TUI-startup paths.
247 - **`src/workspace.rs`** — the directories the session treats as project roots. An editor can
248 open several at once (Zed calls it a multi-root project) and ACP carries the extras as
249 `additional_directories` on every session request; the headless CLI takes them as repeatable
250 `--add-dir` flags. A client only sends those extras to an agent that advertises
251 `sessionCapabilities.additionalDirectories` in its `initialize` reply, so that capability in
252 `handle_initialize` is what makes the rest of this reachable — without it Zed keeps the first
253 root, drops the others, and shows "This agent doesn't currently support multi-root workspaces".
254 The process still has one working directory, so the extra roots live in a
255 process-global here and `project_dirs()` returns cwd-first, extras after.
256 One process also serves every thread the editor has open, so that global
257 (with the cwd, the backend conversation, and the background-task owner in
258 `tools.rs`) always belongs to the *live* session: `main.rs` keeps a
259 `SessionState` per session id and `activate_session` parks the live one and
260 installs the requested one before any prompt or config change runs. Don't
261 read another session's roots from the global. Project-local
262 discovery reads it: skills, slash commands, subagent types, and instruction files all scan
263 every root. MCP is deliberately not on that list — `mcp::init` runs once at startup, before
264 any session exists, so a second root's `.sigit/mcp.toml` has nobody to tell.
265 - **`src/chat.rs`** — the Unix-only ratatui TUI. Loading-spinner phase then chat; uses
266 `tokio::select!` to multiplex terminal events with streaming tokens.
267 - **`src/headless.rs`** — non-interactive `sigit run` execution for scripts, CI, and Factory
268 clients. The legacy `-p` form reaches the same parser. Every new run gets a UUID session id;
269 `--resume <id>` restores that session through `session_store`, and `--output jsonl` emits a
270 structured session/delta/tool/result stream while logs stay on stderr. Headless permission
271 prompts collapse to denial unless the tool was pre-approved with `--allow-tool`.
272 - **`src/session_store.rs`** — durable conversations: one JSON-lines history file per session at
273 `$SIGIT_CONFIG_DIR/sessions/<id>.jsonl`, written atomically, restorable into either backend.
274 Each save also writes a `<id>.meta.json` sidecar naming the session's `cwd` and the extra roots
275 of a multi-root project. That sidecar is what makes a thread *listable*: ACP's `session/list`
276 (advertised as `sessionCapabilities.list`, handled by `handle_list_sessions` in `main.rs` — the
277 editor's "Import Threads" picker) must report an absolute `cwd` per session and may filter on
278 it, so a session without one is skipped there while still reopening by id through
279 `session/load`. Sidecars are written at save time, not at session start, so a thread nobody
280 spoke in leaves nothing behind.
281 - **`src/setup.rs`** — model cache location, local model discovery, selected-model persistence.
282 Must run (`setup_shared_model_cache`) *before* anything touches `ChatEngine`/`hf-hub`, since
283 those read env vars once at init.
284 - **`src/account.rs`** — siGit Code Cloud auth (`/login`, `/logout`, `/whoami`); authenticates
285 against the account API and stores a session token. Performs no console I/O.
286 - **`src/browser_auth.rs`** — browser sign-in, the path the editor's "Sign in to siGit Code"
287 button takes. sigit is a public OAuth client (client id `sigit-code-cli`, no secret, PKCE
288 S256) against the authorization server at `$SIGIT_API_URL/oauth`. Two ways the code gets
289 back: a loopback listener on `127.0.0.1:0` (the registration lists `http://127.0.0.1/callback`
290 with no port, and RFC 8252 §7.3 matching ignores the port, so one registration covers every
291 run), or the out-of-band URN, where the server renders the code and the user pastes it. The
292 resulting token goes into `credentials` like any other, and is served by `/api/v1/user` rather
293 than the deprecated `/api/v1/me` — OAuth tokens are rejected there. The scopes requested are
294 `user:read code:agent`; `code:agent` is what reaches `chat/completions` and the official MCP
295 server. Surfaces: ACP `authenticate` (loopback only — nowhere to show a code), a bare `/login`
296 in either chat surface, and `sigit login` (which adds the paste fallback, plus `--paste` to
297 force it and `--password` for the old email/password prompt).
298 - **`src/credentials.rs`** — local session-token store (TOML, `0600` on Unix).
299 - **`src/models.rs`** — model-picker types shared across platforms.
300
301 Slash commands (`/help`, `/models`, `/skills`, `/agents`, `/commands`, `/mcp`, `/login`, `/logout`,
302 `/whoami`, `/reload`, `/plan`, `/permissions`, `/init`, `/clear`, `/status`) are advertised via
303 `advertise_commands` in `main.rs` and handled in both the TUI and ACP sessions. `/init` is
304 special: instead of replying directly it substitutes `instructions::INIT_PROMPT` for the user
305 text and runs a normal agent turn that explores the repo and writes (or improves) `AGENTS.md`
306 through the ordinary tools and permission checks. User-defined commands (see `src/commands.rs`)
307 get the same treatment via the `SlashCommand::Unknown` fallback path, so anyone can add their own
308 `/name` commands without touching the built-in command list.
309
310 ## Model cache (macOS)
311
312 On macOS the HF model cache lives in an App Group container shared with the siGit desktop app:
313 `~/Library/Group Containers/group.com.ondeinference.apps/models/`. Other platforms fall back to
314 `~/.cache/huggingface/`. The CLI reuses a model the desktop app already downloaded. First run
315 downloads a GGUF model (~1–2 GB) from Hugging Face.
316
317 ## Logging
318
319 In TTY (interactive) mode, *all* output — `log`, `tracing`, stray `println!` — is redirected to
320 `$TMPDIR/sigit.log` so the ratatui surface stays clean; the TUI holds a separate fd to the real
321 terminal. In ACP mode, stdout is reserved for protocol JSON and logs go to stderr. Control
322 verbosity with `RUST_LOG`.
323
324 ## Relevant env vars
325
326 `OPENAI_BASE_URL` / `OPENAI_API_KEY` (provider override), `SIGIT_API_URL` (account API base,
327 default `https://sigit.si`), `SIGIT_CLOUD_URL`, `SIGIT_CONFIG_DIR` (default `~/.config/sigit`),
328 `SIGIT_MODEL`, `SIGIT_MCP` (`off` disables MCP), `SIGIT_MCP_SMBCLOUD` (`off` drops the baked-in
329 smbCloud CLI server), `SIGIT_MCP_OFFICIAL` (`off` drops the baked-in
330 server), `SIGIT_PERMISSIONS` (`allow`/`ask`/`deny` — overrides the default permission mode for
331 mutating tools; the escape hatch for clients without permission-request support),
332 `HF_HOME` / `HF_HUB_CACHE`, `RUST_LOG`.
333
334 ## Releasing
335
336 Version lives in `Cargo.toml`. Update `CHANGELOG.md` for releases.
337
338 Publishing splits into two groups. **Language registries** each get their own tag-triggered
339 workflow: `release-crates`, `release-npm`, `release-nuget`, `release-pypi`. The `npm/`, `nuget/`,
340 and `pypi/` dirs hold their wrapper-package templates.
341
342 npm and NuGet authenticate with OIDC (Trusted Publishing), so neither needs a stored token. On
343 npm that is configured per package, not per org: all seven `@getsigit/*` names carry a trusted
344 publisher pointing at `release-npm.yml`, and a package added later needs the same setup or its
345 publish step will fail. OIDC also requires npm >= 11.5.1 and Node >= 22.14.0, which is why the
346 workflow upgrades npm and why `.nvmrc` cannot drop below 22.
347
348 **OS package managers** all publish somewhere outside this repo and all need checksums from the
349 GitHub release, so `release-github` builds the binaries, attaches the assets, and then dispatches
350 `release-homebrew`, `release-scoop`, `release-winget`, and `release-aur`. A dispatch failure in one
351 is logged as a warning rather than failing the others, so an unconfigured channel does not block a
352 release. Their inputs live in `packaging/`.
353
354 Every release asset now carries a `.sha256` sidecar, not just the macOS Homebrew tarball. Scoop,
355 winget, and the AUR PKGBUILD each need one, and they consume the raw binaries rather than the
356 tarball. `release-github` also builds a `.deb` and `.rpm` per Linux target with nfpm
357 (`packaging/nfpm.yaml`), packaging the already-built binary rather than re-invoking cargo.
358
359 Re-pushing a tag fires every release workflow a second time, so each one is grouped by tag in a
360 `concurrency` block with `cancel-in-progress: false` — the duplicate queues behind the original
361 rather than interrupting a publish that is halfway through uploading. What keeps the queued run
362 from going red is the "is this version already published?" check each publishing workflow does
363 before it uploads. Those checks are load-bearing, not belt-and-braces: v1.5.6 published twice
364 because the crates.io one asked the API with curl's default User-Agent, which crates.io answers
365 with a 403, which read as "not published yet".
366
367 Three of these need credentials or a one-time manual step before they work:
368
369 - Scoop needs a `getsigit/scoop-bucket` repo and a `SCOOP_BUCKET_TOKEN` secret, mirroring the
370 Homebrew tap setup.
371 - winget needs a `WINGET_TOKEN` (PAT with `public_repo`) so `wingetcreate` can fork
372 `microsoft/winget-pkgs`. It is passed as `WINGET_CREATE_GITHUB_TOKEN` rather than `--token`,
373 which wingetcreate warns can leak the token into logs. `wingetcreate update` only works on a
374 package that already exists in `microsoft/winget-pkgs`, so the workflow checks the
375 `manifests/g/getSigit/siGitCode` path first and falls back to rendering
376 `packaging/winget/*.yaml.in` and running `wingetcreate submit` for a first submission. That
377 fallback runs once, then every later release takes the `update` path.
378 - The AUR needs `AUR_USERNAME`, `AUR_EMAIL`, and `AUR_SSH_PRIVATE_KEY`. It publishes `sigit-bin`
379 (a prebuilt binary) so Arch users are not compiling the on-device inference stack to install a
380 CLI.
381
382 `[profile.release]` sets `strip = "symbols"` because binary size is a distribution constraint, not
383 just a nicety. See the NuGet note below.
384
385 The NuGet package (`SiGit.Code`, installed with `dotnet tool install --global SiGit.Code`) is the
386 odd one out among the language registries: npm and PyPI publish one artifact per platform, but a
387 .NET tool is a single package, so `nuget/sigit/` bundles all six binaries under
388 `native/<os>-<arch>/` and a small managed shim (`Program.cs`) execs the right one. That shim leaves
389 stdin/stdout/stderr unredirected on purpose, since siGit Code chooses TUI or ACP mode by testing
390 whether stdin is a TTY. It also sets `RollForward=Major`: it targets `net8.0`, and without that a
391 machine carrying only the .NET 10 runtime installs a tool that refuses to start.
392
393 Bundling every target means the package is large, so `release-nuget.yml` fails the pack job if the
394 `.nupkg` crosses nuget.org's 250 MB limit. At v1.5.1 it lands around 160 MB. If a future release
395 trips that check, the fix is not to drop targets but to split into RID-specific tool packages
396 (.NET 10's `DotnetToolRidPackage`), which ship one binary per platform the way npm already does.
397 That also needs a fallback package for pre-.NET-10 SDKs.