4141
4242# ** Air**   ; 🪁
4343
44+ The Native Background Daemon for Land 🏞️
45+
4446> ** VS Code cold-starts slowly because everything initializes fresh each launch.
4547> Updates require a full restart that kills open terminals and in-progress work.
4648> There is no mechanism to pre-stage work between sessions.**
@@ -52,31 +54,65 @@ update. No restart prompt ever."_
5254[ <img src =" https://editor.land/Image/Rust.svg " width =" 14 " alt =" Rust " />] ( https://www.rust-lang.org/ )   ; [ ![ Crates.io] ( https://img.shields.io/crates/v/Air.svg )] ( https://crates.io/crates/Air )
5355[ <img src =" https://editor.land/Image/Rust.svg " width =" 14 " alt =" Rust " />] ( https://www.rust-lang.org/ )   ; [ ![ Rust Version] ( https://img.shields.io/badge/Rust-1.75+-orange.svg )] ( https://www.rust-lang.org/ )
5456
55- Air is a persistent background daemon that keeps running after you close the
56- editor. It pre-downloads and PGP-verifies the next version between sessions,
57- pre-indexes workspace changes while the editor is closed, and keeps language
58- server warm caches available. When you launch Land, the expensive work is
59- already done. Cold start under 200 ms. Updates apply between sessions with no
60- interruption.
61-
6257📖 ** [ Rust API Documentation] ( https://Rust.Documentation.Editor.Land/Air/ ) **
6358
59+ Welcome to ** Air** , the lightweight, persistent daemon that powers the
60+ background capabilities of the ** Land Code Editor** . While ` Mountain ` handles
61+ the core application logic and UI, ** Air** operates as a specialized sidecar
62+ process dedicated to heavy lifting, network operations, and system maintenance.
63+ It ensures that the main editor remains responsive by offloading
64+ resource-intensive tasks such as updates, large downloads, and cryptographic
65+ signing.
66+
67+ ** Air** acts as the silent partner to ` Mountain ` , providing a robust server
68+ environment that persists even when the main editor window is closed, enabling
69+ seamless background updates and persistent state management.
70+
6471---
6572
66- ## What It Does  ; 🔐
73+ ## Key Features  ; 🔐
74+
75+ - ** Native Sidecar Architecture:** Runs as a standalone process alongside the
76+ main ` Mountain ` application, communicating via high-performance IPC
77+ (gRPC/Vine) to handle requests without blocking the UI thread.
78+ - ** Dedicated Update Management:** Takes full control of the update lifecycle,
79+ including downloading, verifying, and applying patches for ` Land ` , ensuring
80+ the editor is always up-to-date without user interruption.
81+ - ** Isolated Authentication & Signing:** Manages sensitive cryptographic
82+ operations, including binary signing and secure login flows, keeping security
83+ logic isolated from the main application view.
84+ - ** Background Downloader:** Implements a resilient download manager for
85+ extensions, language servers, and dependencies, capable of pausing, resuming,
86+ and handling network interruptions gracefully.
87+ - ** Resource Offloading:** Acts as the designated handler for any "heavy" task
88+ that doesn't strictly require the main application loop, effectively
89+ decoupling infrastructure maintenance from the user experience.
90+
91+ ---
92+
93+ ## Deep Dive & Component Breakdown  ; 🔬
94+
95+ To understand how ` Air ` 's internal components interact to provide the background
96+ daemon functionality, see the following source files:
97+
98+ - ** [ ` Source/ ` ] ( https://github.com/CodeEditorLand/Air/tree/Current/Source/ ) ** -
99+ Main daemon implementation
100+ - ** [ ` Source/Update/ ` ] ( https://github.com/CodeEditorLand/Air/tree/Current/Source/Update/ ) ** -
101+ Update lifecycle management
102+ - ** [ ` Source/Download/ ` ] ( https://github.com/CodeEditorLand/Air/tree/Current/Source/Download/ ) ** -
103+ Resilient download manager
104+ - ** [ ` Source/Auth/ ` ] ( https://github.com/CodeEditorLand/Air/tree/Current/Source/Auth/ ) ** -
105+ Authentication and cryptographic signing
67106
68- - ** Pre-staged updates.** The next version is downloaded, PGP-verified, and
69- ready before you decide to update.
70- - ** Pre-indexed workspaces.** File changes that happened while the editor was
71- closed are already indexed.
72- - ** Warm language server caches.** IntelliSense is ready before you finish the
73- first keystroke.
74- - ** No restart prompt.** Updates apply between sessions. You never see 'Restart
75- to Update'.
107+ The source files explain the gRPC server implementation, task delegation from
108+ Mountain, and the progress event emission patterns.
76109
77110---
78111
79- ## In the Ecosystem  ; 🪁 + 🏞️
112+ ## System Architecture Diagram  ; 🏗️
113+
114+ This diagram illustrates how ** Air** sits alongside ` Mountain ` to handle
115+ background operations.
80116
81117``` mermaid
82118graph LR
@@ -117,18 +153,47 @@ graph LR
117153
118154---
119155
120- ## Development   ; 🛠 ️
156+ ## ` Air ` in the Land Ecosystem   ; 🪁 + 🏞 ️
121157
122- Air is a component of the Land workspace. Follow the
123- [ Land Repository] ( https://github.com/CodeEditorLand/Land ) instructions to build
124- and run.
158+ | Component | Role \& Key Responsibilities |
159+ | :------------------ | :----------------------------------------------------------------------------------- |
160+ | ** Daemon Process** | The persistent executable that runs independently of the main window. |
161+ | ** Server Host** | Hosts a local server to accept commands from ` Mountain ` or other authorized clients. |
162+ | ** Update Delegate** | The sole authority for modifying the installation files of the parent application. |
163+ | ** Signer** | Handles cryptographic signing of artifacts and secure token storage for user login. |
164+ | ** Traffic Manager** | Acts as a proxy/downloader to keep network load off the main renderer process. |
125165
126166---
127167
128- ## License  ; ⚖️
168+ ## Getting Started  ; 🚀
169+
170+ ### Installation  ; 📥
171+
172+ To add ` Air ` to your project workspace:
173+
174+ ``` toml
175+ [dependencies ]
176+ Air = { git = " https://github.com/CodeEditorLand/Air.git" , branch = " Current" }
177+ ```
178+
179+ ### Usage Pattern  ; 🚀
180+
181+ ** Air** is typically spawned automatically by ` Mountain ` during the startup
182+ phase.
183+
184+ 1 . ** Spawn:** ` Mountain ` detects if ` Air ` is running. If not, it spawns the
185+ binary.
186+ 2 . ** Connect:** ` Mountain ` establishes a Vine (gRPC) connection to ` Air ` 's local
187+ port ` [::1]:50053 ` (reserved for Air, separate from Cocoon's port 50052).
188+ 3 . ** Delegate:** When a user requests an update or a large download, ` Mountain `
189+ sends a command to ` Air ` and immediately returns control to the user.
190+ 4 . ** Monitor:** ` Air ` emits progress events back to ` Mountain ` to update the UI
191+ status bars.
129192
130- CC0 1.0 Universal. Public domain. No restrictions.
131- [ LICENSE] ( https://github.com/CodeEditorLand/Air/tree/Current/LICENSE )
193+ ### Port Allocation
194+
195+ - ** Air** : Port ` 50053 ` (Vine/Air.proto protocol - Air daemon services)
196+ - ** Cocoon** : Port ` 50052 ` (Vine.proto protocol - VS Code extension hosting)
132197
133198---
134199
@@ -138,24 +203,30 @@ CC0 1.0 Universal. Public domain. No restrictions.
138203- [ Architecture Overview] ( https://editor.land/Doc/architecture )
139204- [ Why Rust] ( https://editor.land/Doc/why-rust )
140205- [ Mountain] ( https://github.com/CodeEditorLand/Mountain )
206+ - [ Vine] ( https://github.com/CodeEditorLand/Vine )
141207- [ Echo] ( https://github.com/CodeEditorLand/Echo )
208+ - [ Mist] ( https://github.com/CodeEditorLand/Mist )
209+
210+ ---
142211
143- ## Changelog 📜
212+ ## License  ; ⚖️
213+
214+ This project is released into the public domain under the ** Creative Commons CC0
215+ Universal** license. You are free to use, modify, distribute, and build upon
216+ this work for any purpose, without any restrictions. For the full legal text,
217+ see the [ ` LICENSE ` ] ( https://github.com/CodeEditorLand/Air/tree/Current/ ) file.
218+
219+ ---
220+
221+ ## Changelog  ; 📜
144222
145223Stay updated with our progress! See
146224[ ` CHANGELOG.md ` ] ( https://github.com/CodeEditorLand/Air/tree/Current/ ) for a
147225history of changes specific to ** Air** .
148226
149227---
150228
151- ## See Also
152-
153- - [ Architecture Overview] ( https://editor.land/Doc/architecture )
154- - [ Mountain] ( https://github.com/CodeEditorLand/Mountain )
155- - [ Vine] ( https://github.com/CodeEditorLand/Vine )
156- - [ Mist] ( https://github.com/CodeEditorLand/Mist )
157-
158- ## Funding \& Acknowledgements 🙏🏻
229+ ## Funding \& Acknowledgements  ; 🙏🏻
159230
160231** Air** is a core element of the ** Land** ecosystem. This project is funded
161232through [ NGI0 Commons Fund] ( https://NLnet.NL/commonsfund ) , a fund established by
0 commit comments