handwrite docs

site/src/pages/architecture.mdx

@@ -1,101 +0,0 @@
----
-layout: ../layouts/DocLayout.astro
-title: Architecture
-toc: true
----
-
-# Architecture
-
-`deskctl` is not trying to be a desktop environment abstraction layer. The
-design goal is a small, unsurprising Linux X11 control primitive that agents
-can discover and compose progressively.
-
-## Public model
-
-The public flow is:
-
-- diagnose with `deskctl doctor`
-- observe with `snapshot`, `list-windows`, and grouped `get` commands
-- wait with grouped `wait` commands instead of shell `sleep`
-- act with explicit selectors or coordinates
-- verify with another read or snapshot
-
-The tool stays intentionally narrow. It does not try to be a full desktop shell
-or a speculative Wayland abstraction.
-
-## Client and daemon
-
-The CLI talks to an auto-managed daemon over a Unix socket. The daemon keeps
-the X11 connection alive so repeated commands stay fast and share the same
-session-scoped window identity map.
-
-Each CLI invocation sends one request, reads one response, and exits.
-
-## Runtime contract
-
-Requests and responses are newline-delimited JSON (NDJSON) over a Unix socket.
-
-All commands share the same JSON envelope:
-
-```json
-{
-  "success": true,
-  "data": {},
-  "error": null
-}
-```
-
-For window payloads, the public identity is `window_id`, not an X11 handle.
-That keeps the contract backend-neutral even though the current support
-boundary is X11-only.
-
-The complete stable-vs-best-effort policy lives on the
-[runtime contract](/runtime-contract) page.
-
-## Sessions and sockets
-
-Each session gets its own socket path, PID file, and live window mapping.
-
-Public socket resolution order:
-
-1. `--socket`
-2. `DESKCTL_SOCKET_DIR/{session}.sock`
-3. `XDG_RUNTIME_DIR/deskctl/{session}.sock`
-4. `~/.deskctl/{session}.sock`
-
-Most users should let `deskctl` manage this automatically. `--session` is the
-main public knob when you need isolated daemon instances.
-
-## Diagnostics and failure handling
-
-`deskctl doctor` runs before daemon startup and checks:
-
-- display/session setup
-- X11 connectivity
-- basic window enumeration
-- screenshot viability
-- socket directory and stale-socket health
-
-Selector and wait failures are structured in `--json` mode so clients can
-recover without scraping text.
-
-## Backend boundary
-
-The backend is built around a `DesktopBackend` trait and currently ships with
-an X11 implementation backed by `x11rb`.
-
-The important public guarantee is not "portable desktop automation." The
-important guarantee is "a correct and unsurprising Linux X11 runtime contract."
-
-## X11 support boundary
-
-This phase supports Linux X11 only.
-
-That means:
-
-- EWMH/window-manager properties matter
-- monitor naming and some ordering details are best-effort
-- Wayland and Hyprland are out of scope for the current contract
-
-The runtime documents those boundaries explicitly instead of pretending the
-surface is broader than it is.

site/src/pages/index.astro

@@ -8,68 +8,43 @@ import DocLayout from "../layouts/DocLayout.astro";
     <img src="/favicon.svg" alt="" width="40" height="40" />
   </header>
 
-  <p class="tagline">non-interactive desktop control for AI agents</p>
+  <p class="tagline">non-interactive desktop control cli for AI agents</p>
 
   <p class="lede">
-    <code>deskctl</code> is a thin X11 control primitive for agent loops: diagnose
+    A thin X11 control primitive for agent loops: diagnose the runtime, observe
-    the runtime, observe the desktop, wait for state transitions, act deterministically,
+    the desktop, wait for state transitions, act deterministically, then verify.
-    then verify.
   </p>
 
-  <pre><code>{`npm install -g deskctl
-deskctl doctor
-deskctl snapshot --annotate`}</code></pre>
-
   <h2>Start</h2>
 
-  <p>
-    Install the CLI, verify the runtime, then run the core observe -&gt; wait
-    -&gt; act -&gt; verify loop.
-  </p>
-
   <ul>
     <li>
-      <a href="/installation">Installation</a> - install paths, runtime requirements,
+      <a href="/installation">Installation</a>
-      and first-run checks
     </li>
     <li>
-      <a href="/quick-start">Quick start</a> - the minimal workflow for real desktop
+      <a href="/quick-start">Quick start</a>
-      control
     </li>
   </ul>
 
   <h2>Reference</h2>
 
-  <p>
-    Read the command surface, the daemon/runtime model, and the stable JSON
-    contract.
-  </p>
-
   <ul>
     <li>
-      <a href="/commands">Commands</a> - grouped reads, waits, actions, selectors,
+      <a href="/commands">Commands</a>
-      and global flags
     </li>
     <li>
-      <a href="/architecture">Architecture</a> - client/daemon model, sessions, sockets,
+      <a href="/runtime-contract">Runtime contract</a>
-      and support boundary
-    </li>
-    <li>
-      <a href="/runtime-contract">Runtime contract</a> - stable JSON fields, errors,
-      and best-effort text behavior
     </li>
   </ul>
 
   <h2>Links</h2>
 
-  <p>
-    The repo is the source of truth for the CLI, the skill, and the release
-    assets.
-  </p>
-
   <ul>
     <li>
       <a href="https://github.com/harivansh-afk/deskctl">GitHub</a>
     </li>
+    <li>
+      <a href="https://www.npmjs.com/package/deskctl">npm</a>
+    </li>
   </ul>
 </DocLayout>

site/src/pages/installation.mdx

@@ -22,23 +22,15 @@ downloading the matching GitHub Release asset for the supported runtime target.
 This path does not require a Rust toolchain. The installed command is always
 `deskctl`, even though the release asset itself is target-specific.
 
-## Quick try without a global install
+## Skill install
+
+The repo skill lives under `skills/deskctl`, so you can install it
+directly uring `skills.sh`
 
 ```sh
-npx deskctl --help
+npx skills add harivansh-afk/deskctl
 ```
 
-This is useful when you only need a temporary run or want to smoke-test a
-machine before deciding how to install it permanently.
-
-## What the npm install does
-
-- downloads the matching GitHub Release asset for the current supported target
-- exposes the public command as `deskctl`
-- keeps the install path operator-friendly: no source build, no manual rename
-
-Today the npm distribution is aimed at Linux x64 X11 environments.
-
 ## Other install paths
 
 ### Nix
@@ -48,7 +40,7 @@ nix run github:harivansh-afk/deskctl -- --help
 nix profile install github:harivansh-afk/deskctl
 ```
 
-### Build from source
+### Rust
 
 ```sh
 git clone https://github.com/harivansh-afk/deskctl
@@ -62,17 +54,6 @@ Source builds on Linux require:
 - `pkg-config`
 - X11 development libraries such as `libx11-dev` and `libxtst-dev`
 
-## Skill install
-
-The repo skill lives under `skills/deskctl`, so `skills` can install it
-directly from this GitHub repo. It is designed around the same observe -> wait
--> act -> verify loop as the CLI. `-g` installs it globally; omit that flag if
-you want a project-local install.
-
-```sh
-npx skills add harivansh-afk/deskctl -s deskctl
-```
-
 ## Runtime requirements
 
 - Linux with an active X11 session
@@ -83,9 +64,9 @@ npx skills add harivansh-afk/deskctl -s deskctl
 
 The binary itself only depends on the standard Linux glibc runtime.
 
-## First troubleshooting step
+## Verification
 
-If setup fails, start here:
+If setup fails for any reason start here:
 
 ```sh
 deskctl doctor

site/src/pages/quick-start.mdx

@@ -6,8 +6,7 @@ toc: true
 
 # Quick start
 
-The fastest way to use `deskctl` is to follow the same four-step loop every
+The fastest way to use `deskctl` is to follow the same four-step loop : observe, wait, act, verify.
-time: observe, wait, act, verify.
 
 ## 1. Install and diagnose
 
@@ -16,7 +15,7 @@ npm install -g deskctl
 deskctl doctor
 ```
 
-Use `deskctl doctor` first. It checks X11 connectivity, basic enumeration,
+Run `deskctl doctor` first. It checks X11 connectivity, basic enumeration,
 screenshot viability, and socket health before you start driving the desktop.
 
 ## 2. Observe the desktop