crynta · vkayonline · Jun 29, 2026
@@ -1,5 +1,5 @@
 <!--
-PR title should follow Conventional Commits — it becomes the squash commit message.
+PR title should follow Conventional Commits - it becomes the squash commit message.
 Examples: feat(terminal): add split panes / fix(explorer): close button alignment
 -->
 
@@ -13,12 +13,15 @@ Examples: feat(terminal): add split panes / fix(explorer): close button alignmen
 <!-- Brief notes on the approach, only if non-obvious. -->
 
 ## Testing
-<!-- How did you verify this works? "Ran tsc clean" is not enough on its own —
+<!-- How did you verify this works? "Ran tsc clean" is not enough on its own -
      describe the actual flows you exercised. -->
 
-- [ ] `pnpm exec tsc --noEmit` clean
+- [ ] `pnpm lint` clean
+- [ ] `pnpm check-types` clean
+- [ ] `pnpm test` clean
 - [ ] Manual smoke-test of the affected feature
-- [ ] (If you touched `src-tauri/`) `cargo test --locked` and `cargo clippy --all-targets --locked -- -D warnings` clean
+- [ ] (If you touched `src-tauri/`) `cargo clippy --all-targets --locked -- -D warnings` clean
+- [ ] (If you touched `src-tauri/`) `cargo nextest run --locked` clean (or `cargo test --locked`)
 - [ ] (If you changed a `#[tauri::command]` signature) called out below so the FE caller can be updated in lockstep
 - [ ] (If UI) tested in `pnpm tauri dev`
 - [ ] Platforms tested: <!-- macOS / Linux / Windows -->

@@ -5,16 +5,16 @@ Terax is a small open-source project and we want it to stay a place people enjoy
 ## The rules, briefly
 
 - **Be respectful.** Disagreement is fine; rudeness, condescension, and personal attacks are not.
-- **Assume good faith.** Most miscommunication isn't malicious — clarify before escalating.
+- **Assume good faith.** Most miscommunication isn't malicious - clarify before escalating.
 - **Stay on topic.** Issues, PRs, and discussions are about Terax. Take off-topic conversations elsewhere.
-- **No harassment.** Targeted insults, slurs, sustained disruption, sexualized comments, doxxing, or threats are not tolerated — anywhere, against anyone.
+- **No harassment.** Targeted insults, slurs, sustained disruption, sexualized comments, doxxing, or threats are not tolerated - anywhere, against anyone.
 - **No spam.** That includes promotional links, irrelevant cross-posting, and AI-generated noise that doesn't engage with the actual conversation.
 
 This applies to everything inside the project: issues, PRs, discussions, commits, and any community space we create later (Discord, etc.).
 
 ## Enforcement
 
-If you see a violation — or experience one — email **crynta.dev@gmail.com** with subject `[Terax conduct]`. Include links and context.
+If you see a violation - or experience one - email **crynta.dev@gmail.com** with subject `[Terax conduct]`. Include links and context.
 
 Maintainers may, at their discretion:
 

@@ -22,6 +22,8 @@ pnpm tauri dev
 
 Prereqs: Rust (stable), Node 20+, pnpm, plus your platform's [Tauri prerequisites](https://tauri.app/start/prerequisites/).
 
+For the architecture and how to contribute safely, see [TERAX.md](TERAX.md) and the [docs/ index](docs/README.md).
+
 ## Where to discuss
 
 Discord: [Crynta OS](https://discord.gg/tyveTUyEp7)
@@ -74,9 +76,12 @@ A 10-minute conversation saves a 500-line PR that doesn't fit the roadmap.
 
 Terax positions itself as **lightweight, fast, production-grade**. Every PR is reviewed against:
 
-- `pnpm exec tsc --noEmit` clean
-- `cargo clippy` clean, `cargo fmt` applied
-- `pnpm test` and `cargo test` pass
+- `pnpm lint` clean
+- `pnpm check-types` clean
+- `pnpm test` clean
+- `cargo clippy --all-targets --locked -- -D warnings` clean
+- `cargo nextest run --locked` clean (or `cargo test --locked`)
+- `cargo fmt` applied before pushing
 - No perf regressions in known hot paths: terminal renderer, PTY stream, AI streaming, source control, file explorer
 - No new heavy dependencies (>50KB gzip in client bundle, >5MB compiled on Rust side) without justification
 - Platform parity preserved (macOS / Linux / Windows / WSL still work)
@@ -179,27 +184,45 @@ Within a PR, individual commit messages can be free-form (they get squashed or g
 
 ```
 src-tauri/                  Rust backend
-  src/modules/
-    pty/                    Terminal sessions, shell integration, DA filter
-    fs/                     File system commands
-    git/                    Source control
-    net/                    AI HTTP proxy with SSRF guard
-    workspace/              WSL bridge, workspace env
-
-src/
+  src/
+    lib.rs                  Tauri command registration
+    modules/
+      agent.rs              Terminal coding-agent hook installer/status
+      fs/                   File system commands (read/write/search/grep)
+      git/                  Source control commands
+      history/              Shell history integration
+      mod.rs                Module exports
+      net.rs                AI HTTP proxy with SSRF guard
+      proc.rs               Process utilities
+      pty/                  Terminal sessions, shell integration, DA filter
+      secrets.rs            OS keychain access
+      shell/                Oneshot/session/background shell commands
+      workspace.rs          WSL bridge, workspace env, authorization registry
+
+src/                        React frontend
+  App.tsx                   Top-level coordinator
+  components/               shadcn/ui + AI Elements
   modules/
-    terminal/               xterm.js sessions, OSC handlers, renderer pool
+    agents/                 Agent notifications and management
+    ai/                     Agents, sessions, tools, providers, composer
+    command-palette/        Modal command palette and actions
     editor/                 CodeMirror stack, AI autocomplete
     explorer/               File tree
-    tabs/                   Tab/split model
-    ai/                     Agents, sessions, tools, providers, mini-window
     git-history/            Git graph and history pane
-    source-control/         Source control panel
-    preview/                Image / Markdown / web preview
+    header/                 Top bar, search, window controls
+    markdown/               Markdown preview renderer
+    preview/                Dev server, image, and web preview
     settings/               Settings UI and preferences store
-    shortcuts/              Keymap
-  app/                      Top-level App.tsx
-  components/               shadcn/ui + AI Elements
+    shortcuts/              Keymap registry
+    sidebar/                Activity bar and side panels
+    source-control/         Source control panel
+    spaces/                 Workspace spaces/projects with per-space tab persistence
+    statusbar/              Bottom bar and cwd breadcrumb
+    tabs/                   Tab/split model
+    terminal/               xterm.js sessions, OSC handlers, renderer pool
+    theme/                  Custom theme engine and presets
+    updater/                Auto-updater UI
+    workspace/              Workspace environment switching
 ```
 
 ## FAQ

@@ -106,7 +106,7 @@ Latest installers are on the [Releases](https://github.com/crynta/terax-ai/relea
 ### Linux notes
 
 - **Arch / AUR:** `yay -S terax-bin` (or `paru`, etc.). Tracks the latest release.
-- **NixOS / Nix**: use the official flake — `nix profile install github:crynta/terax-ai` (non-NixOS), or import the flake and add `inputs.terax.packages.${pkgs.system}.terax` to `environment.systemPackages` (NixOS). The `nixosModules.terax` output is also available for a simpler setup.
+- **NixOS / Nix**: use the official flake - `nix profile install github:crynta/terax-ai` (non-NixOS), or import the flake and add `inputs.terax.packages.${pkgs.system}.terax` to `environment.systemPackages` (NixOS). The `nixosModules.terax` output is also available for a simpler setup.
 - **AppImage:** needs FUSE. Without it: `./Terax_*.AppImage --appimage-extract-and-run`. On Wayland with rendering glitches, try `WEBKIT_DISABLE_DMABUF_RENDERER=1`. Otherwise the `.deb` / `.rpm` packages link against the system GTK stack and tend to be smoother.
 
 ## Configure AI
@@ -131,9 +131,11 @@ pnpm tauri build        # production bundle
 
 **Checks**
 ```bash
-pnpm exec tsc --noEmit                                            # frontend type-check
-cd src-tauri && cargo clippy --all-targets --locked -D warnings   # Rust lint (matches CI)
-cd src-tauri && cargo test --locked                               # Rust tests
+pnpm lint
+pnpm check-types
+pnpm test
+cd src-tauri && cargo clippy --all-targets --locked -- -D warnings   # Rust lint (matches CI)
+cd src-tauri && cargo nextest run --locked                           # or: cargo test --locked
 ```
 
 ## Tech stack
@@ -142,7 +144,7 @@ Tauri 2, Rust, `portable-pty`, React 19, TypeScript, Vite, xterm.js, CodeMirror
 
 ## Contributing
 
-Issues and PRs are welcome! Feel free to open issues, suggest features, or submit pull requests. See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
+Issues and PRs are welcome! Feel free to open issues, suggest features, or submit pull requests. See [CONTRIBUTING.md](CONTRIBUTING.md) and the [architecture docs](docs/README.md) for more details.
 
 ## License
 

@@ -1,6 +1,6 @@
 # Security
 
-Terax runs shells, reads/writes files, and talks to AI providers — so security bugs matter. If you find one, please tell us before posting it publicly.
+Terax runs shells, reads/writes files, and talks to AI providers, so security bugs matter. If you find one, please tell us before posting it publicly.
 
 ## Reporting
 
@@ -10,30 +10,30 @@ Email **security@terax.app**. Include:
 - Steps to reproduce (a small PoC is great)
 - Version, OS, arch
 
-We'll get back to you within a few days. Once it's fixed, we'll credit you in the release notes — unless you'd rather stay anonymous.
+We'll get back to you within a few days. Once it's fixed, we'll credit you in the release notes - unless you'd rather stay anonymous.
 
 Please **don't** open a public GitHub issue for security reports.
 
 ## Supported versions
 
-Until `1.0.0`, only the latest minor gets security fixes. Right now that's `0.5.x`. 
+Until `1.0.0`, only the latest minor gets security fixes. See the current version in `package.json` or on the [Releases page](https://github.com/crynta/terax-ai/releases). 
 
 ## What's in scope
 
 - The Rust backend in `src-tauri/` (PTY, FS, IPC, plugins)
-- The frontend in `src/` — anywhere untrusted input lands (terminal output, file content, AI tool results, credentials)
+- The frontend in `src/` - anywhere untrusted input lands (terminal output, file content, AI tool results, credentials)
 - Release artifacts on GitHub and `terax.app`
 - The auto-updater
 
 ## What's not
 
-- Bugs in upstream deps (Tauri, xterm.js, CodeMirror, AI SDKs…) — report those upstream. We'll ship the fix once it's released.
+- Bugs in upstream deps (Tauri, xterm.js, CodeMirror, AI SDKs…) - report those upstream. We'll ship the fix once it's released.
 - Anything that needs an already-compromised machine or a local attacker with shell access
 - Older versions (`< 0.5`)
 
 ## What we do to keep things safe
 
-- **API keys** live in the OS keychain via `keyring` — not on disk, not in `localStorage`, not in logs.
+- **API keys** live in the OS keychain via `keyring` - not on disk, not in `localStorage`, not in logs.
 - **No telemetry.** Terax only talks to the network when you ask it to (AI requests, update checks, web preview).
 - **AI tool approval.** File writes and shell commands from the agent need your OK before they run.
 - **No Node in the renderer.** The frontend only reaches the host through the allow-listed Tauri commands.
@@ -43,4 +43,4 @@ Until `1.0.0`, only the latest minor gets security fixes. Right now that's `0.5.
 
 - Terax runs whatever you (or the agent) tell it to run, with your permissions. That's kind of the point of a terminal.
 - AI providers see whatever you send them. Read their retention policies.
-- Local LLM endpoints (LM Studio, OpenAI-compatible) are trusted at the network level — only point Terax at servers you control.
+- Local LLM endpoints (LM Studio, OpenAI-compatible) are trusted at the network level - only point Terax at servers you control.