twisk 0.1.0b0__tar.gz

twisk-0.1.0b0/LICENSE

@@ -0,0 +1,199 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. Please also get an OpenPGP
+      key ID and put it in the key field.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

twisk-0.1.0b0/PKG-INFO

@@ -0,0 +1,360 @@
+Metadata-Version: 2.4
+Name: twisk
+Version: 0.1.0b0
+Summary: A k9s-style terminal UI for SkyPilot: clusters, managed jobs, services and volumes without hand-written YAML
+Keywords: skypilot,tui,k9s,ml,gpu,kubernetes,cloud
+Author: Reda Oulbacha
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Clustering
+Classifier: Topic :: System :: Systems Administration
+Requires-Dist: textual>=8,<9
+Requires-Dist: rich>=13
+Requires-Dist: pydantic>=2,<3
+Requires-Dist: pyyaml>=6,<7
+Requires-Dist: jinja2>=3.1,<4
+Requires-Dist: typer>=0.12
+Requires-Dist: skypilot>=0.14.2,<0.15
+Requires-Python: >=3.10, <3.14
+Project-URL: Homepage, https://github.com/roulbac/twisk
+Project-URL: Repository, https://github.com/roulbac/twisk
+Project-URL: Issues, https://github.com/roulbac/twisk/issues
+Description-Content-Type: text/markdown
+
+# twisk
+
+**A k9s-style terminal UI for [SkyPilot](https://github.com/skypilot-org/skypilot).** *(twisk = TUI + sky)*
+Browse and drive clusters, managed jobs, services and volumes from one keyboard-driven screen, and create them
+through forms instead of hand-writing YAML.
+
+![twisk demo: creating a cluster from a form, following its launch, then GPU usage and the spec library](https://raw.githubusercontent.com/roulbac/twisk/main/docs/assets/twisk-demo.gif)
+
+<sub>Recorded with `twisk --demo` (an in-memory simulation). Regenerate with `scripts/capture_screenshots.py`.</sub>
+
+## Why
+
+SkyPilot is configured with task YAML. That's powerful, but for day-to-day work you end up keeping a folder of
+half-remembered YAML files and a terminal full of `sky status`, `sky logs`, `sky jobs queue`… twisk keeps the power
+and removes the bookkeeping:
+
+- **Forms, not YAML.** Press `c` anywhere to create a cluster, managed job, service or volume. Each form validates as
+  you type and shows the exact SkyPilot YAML it generates in a live preview pane.
+- **Forms you define.** Every form is a template in `~/.twisk/templates` — a list of fields plus a Jinja2 template
+  that turns them into SkyPilot YAML. Write your team's "GPU dev box" or "nightly eval" form once; everyone gets a
+  form with just the knobs that matter and your defaults baked in. See [Form templates](#form-templates).
+- **A spec library you never have to manage, but can.** Everything you create is saved as plain SkyPilot YAML under
+  `~/.twisk/specs/<kind>/<name>.yaml`. Press `e` to re-open the form, `E` to edit the YAML in twisk's built-in vim
+  editor, `R` to relaunch from it. Fields the form doesn't know about (e.g. `file_mounts`,
+  `instance_type`, `config:`) are preserved across form edits. The files work with the plain CLI too:
+  `sky launch -c dev ~/.twisk/specs/clusters/dev.yaml`.
+- **Everything in one place, live.** Clusters, cluster job queues, managed jobs, services and their replicas, job
+  pools and their workers, volumes, storage buckets, GPU usage, in-flight API requests, enabled infra and
+  workspaces — auto-refreshing, filterable, sortable.
+- **GPU-hours and idle time, not dollars.** Every cluster shows its GPU count, GPU-hours so far and how long it has
+  been idle (busy while jobs run; otherwise idle since its last job ended, the same notion SkyPilot's autostop uses).
+  GPU clusters idle for an hour or more are flagged red, and the title bar counts GPUs up vs. GPUs sitting idle.
+  `:usage` lists GPU-hours per cluster — including torn-down ones — over 1d/7d/30d/all. No prices are shown:
+  Kubernetes has none unless an admin configures them. (Interactive SSH sessions aren't visible to twisk, so a
+  cluster someone is using only over SSH reads as idle.)
+- **Mine vs. everyone, and workspaces.** `U` toggles between your resources and every user's (default: yours, so
+  `ctrl-d` isn't one key from a teammate's cluster). `:ws` lists workspaces; `enter` switches the one new launches go
+  to (via a SkyPilot project-config overlay — your `~/.sky/config.yaml` is never edited).
+- **Knows SkyPilot's sharp edges.** e.g. Kubernetes clusters can only auto-*down*, never stop; a service's port has
+  to be both `service.ports` and an opened resource port. twisk checks these as you type — in the built-in forms,
+  your own templates and the YAML editor alike — so launches don't fail late.
+- **Logs and shells one key away.** `l` streams logs (cluster jobs, managed jobs, controllers, load balancers,
+  replicas, API requests); `s` drops you into an SSH shell on a cluster; `x` runs a command with `sky exec`.
+- **Safe by default.** Destructive actions are on `ctrl-d` and always confirm. twisk never auto-starts a local API
+  server behind your back; it tells you when the server is unreachable instead.
+
+## Screenshots
+
+| | |
+|---|---|
+| ![Clusters with GPU count, GPU-hours and idle time](https://raw.githubusercontent.com/roulbac/twisk/main/docs/assets/clusters.png) | ![Create form with live YAML preview](https://raw.githubusercontent.com/roulbac/twisk/main/docs/assets/create-form.png) |
+| **Clusters.** GPUs, GPU-hours and idle time per cluster; idle GPU clusters in red, "9 GPUs up · 8 idle ≥1h" in the title. | **Forms, not YAML.** Fill fields, see the exact SkyPilot YAML on the right; `ctrl-s` saves and launches. |
+| ![Launch output streaming](https://raw.githubusercontent.com/roulbac/twisk/main/docs/assets/launch-logs.png) | ![GPU usage over the last 30 days](https://raw.githubusercontent.com/roulbac/twisk/main/docs/assets/usage.png) |
+| **Launch logs.** SkyPilot's output streams in, then the job's own output. `esc` detaches; the launch keeps going. | **GPU usage.** GPU-hours per cluster, including torn-down ones, over 1d / 7d / 30d / all. |
+| ![Spec library](https://raw.githubusercontent.com/roulbac/twisk/main/docs/assets/specs.png) | ![Built-in YAML editor](https://raw.githubusercontent.com/roulbac/twisk/main/docs/assets/yaml-editor.png) |
+| **Spec library.** Everything you create, as plain SkyPilot YAML in `~/.twisk/specs`. | **Escape hatch.** `E` (or `ctrl-e` in a form) opens the YAML in a built-in vim editor; it's validated on `:w`. |
+| ![Form templates](https://raw.githubusercontent.com/roulbac/twisk/main/docs/assets/templates.png) | ![A form generated from a custom template](https://raw.githubusercontent.com/roulbac/twisk/main/docs/assets/custom-form.png) |
+| **Form templates.** Built-in forms and your own, side by side (`:templates`). | **Your own forms.** A team template: five fields, the rest of the YAML baked in. |
+
+## Install & run
+
+twisk is on [PyPI](https://pypi.org/project/twisk/). Install it as a command-line tool with
+[uv](https://docs.astral.sh/uv/getting-started/installation/):
+
+```bash
+uv tool install twisk==0.1.0b0
+twisk --demo          # try it against an in-memory simulation, no server needed
+twisk                 # TUI against your SkyPilot API server
+```
+
+0.1.0b0 is a beta (a pre-release), so name the version or allow pre-releases — `uv tool install twisk` alone only
+picks stable releases. uv picks a supported Python (3.10–3.13) by itself. Other ways to get it:
+
+```bash
+uv tool install --prerelease allow twisk                             # latest, including betas
+uvx --from twisk==0.1.0b0 twisk --demo                                # run once without installing
+uv tool upgrade --prerelease allow twisk                              # update
+uv tool install git+https://github.com/roulbac/twisk                  # straight from main
+pipx install twisk==0.1.0b0                                           # or with pipx / pip
+uv tool uninstall twisk
+```
+
+From a checkout (for development), use `uv sync` and prefix commands with `uv run` (`uv run twisk --demo`).
+
+twisk talks to a [SkyPilot API server](https://docs.skypilot.co/en/latest/reference/api-server/api-server.html).
+The endpoint is resolved in this order: `--endpoint URL`, `$SKYPILOT_API_SERVER_ENDPOINT`, `endpoint:` in
+`~/.twisk/config.yaml`, `api_server.endpoint` in `~/.sky/config.yaml` (what `sky api login` writes), then
+`http://127.0.0.1:46580`.
+
+## Try it: the k3s sandbox
+
+`twisk sandbox` gives you a disposable SkyPilot setup on your laptop: a single-node k3s cluster and a SkyPilot API
+server wired to it, both in Docker. Nothing touches your real clouds.
+
+```bash
+twisk sandbox up       # ~3–5 min the first time (pulls k3s, SkyPilot and the SkyPilot pod image)
+twisk                  # the sandbox is now twisk's default endpoint
+twisk sandbox status
+twisk sandbox start    # after a reboot / Docker restart
+twisk sandbox down     # removes everything
+```
+
+Requirements: Docker with ~4 CPUs / 8 GB available. In the sandbox use `infra: k8s` (or leave infra empty), keep
+requests small (1 CPU / 1–2 GB), and note that Kubernetes clusters can be torn down but not stopped.
+
+| | |
+|---|---|
+| API server | `http://127.0.0.1:46580` (also usable with the plain `sky` CLI via `SKYPILOT_API_SERVER_ENDPOINT`) |
+| kubeconfig | `~/.twisk/sandbox/kubeconfig` (`kubectl --kubeconfig ~/.twisk/sandbox/kubeconfig get pods`) |
+| server logs | `twisk sandbox logs` |
+| service endpoints | SkyServe load balancers listen on `http://localhost:30001`–`30020` (published from the sandbox) |
+| pod images | `twisk sandbox preload [IMAGE…]` side-loads images from your host's Docker into k3s |
+| workspaces | `default` and `experiments`, to try workspace switching (`:ws`) |
+
+What `sandbox up` does: starts `rancher/k3s` (API on `127.0.0.1:16443`), starts `berkeleyskypilot/skypilot:0.14.2`
+with `sky api start --deploy` in the k3s container's network namespace, gives the server the k3s kubeconfig plus a
+small config (managed-jobs/serve controllers run inside the API server; pods use `imagePullPolicy: IfNotPresent`),
+pre-loads SkyPilot's pod image into k3s from your host's Docker cache (so recreating the sandbox doesn't re-download
+it), runs `sky check kubernetes`, and points twisk at it. It detects cgroup-v1 hosts and nested-container hosts that
+forbid lowering `oom_score_adj` and adjusts k3s accordingly.
+
+The sandbox is one k3s node with whatever CPUs Docker gives it. If a launch sits in INIT or fails with
+"Failed to acquire resources", the node is full: tear down clusters/services you no longer need (`ctrl-d`).
+
+Behind a TLS-intercepting corporate proxy, pass a CA bundle that includes your proxy's CA:
+`twisk sandbox up --ca-bundle /path/to/ca-bundle.crt`. It is trusted by k3s (image pulls), the API server (catalog
+downloads) and every SkyPilot pod (pip/uv/curl during runtime setup).
+
+## Keys
+
+| Global | |
+|---|---|
+| `:` | command mode: `:clusters` `:jobs` `:services` `:pools` `:volumes` `:storage` `:usage` `:specs` `:requests` `:infra` `:ws` `:templates` `:q` (aliases: `cl`, `mj`, `svc`, `pl`, `vol`, `st`, `gpu`, `sp`, `req`, `tpl`, …) |
+| `1`–`9`, `0` | jump to a view: clusters, jobs, services, pools, volumes, storage, usage, specs, requests, infra |
+| `j` `k` · `g` `G` | move down / up · to top / bottom (arrows work too) |
+| `U` | scope: only my resources ⇄ every user's |
+| `/` | filter rows, `esc` clears |
+| `<` `>` | sort by previous/next column (again to reverse) |
+| `ctrl-r` | refresh now (on clusters: ask the clouds for fresh status) |
+| `esc` / `q` | back (q quits at the top level) · `?` help · `ctrl-c` quit |
+
+| Clusters | | Managed jobs | |
+|---|---|---|---|
+| `c` | create (form) | `c` | submit (form) |
+| `enter` | job queue on the cluster | `l` / `enter` | job logs |
+| `l` | logs of the latest job | `L` | controller logs |
+| `s` | SSH shell | `ctrl-d` | cancel |
+| `x` | `sky exec` a command | `R` | resubmit from spec |
+| `p` / `u` | stop / start | | |
+| `a` | autostop / autodown | **Services** | |
+| `ctrl-d` | tear down | `enter` | replicas (`l` logs, `ctrl-d` terminate) |
+| `d` / `y` | describe / YAML | `l` / `L` | load balancer / controller logs |
+| `e` / `E` | edit spec in form / as YAML | `e` / `R` | edit, rolling update |
+| `R` | relaunch from spec | `ctrl-d` | tear down |
+| `i` | import the server's YAML into the library | | |
+
+| Spec library (`8`) | | Requests (`9`) | |
+|---|---|---|---|
+| `enter` | launch / apply | `enter` | follow logs |
+| `e` / `E` | edit in form / as YAML | `ctrl-d` | cancel |
+| `D` | duplicate | | |
+| `ctrl-d` | delete the file | **Forms** | |
+| `o` | show (and copy) the path | `ctrl-s` | save spec + launch/apply |
+| | | `ctrl-o` / `ctrl-e` | save only / continue in the vim editor |
+| | | `c` (any view) | new resource; asks which form if a kind has several templates |
+
+| Pools (`4`) | | GPU usage (`7`) | |
+|---|---|---|---|
+| `c` | create (form) | `t` | cycle window: 1d / 7d / 30d / all |
+| `enter` | workers (`l` worker logs) | `d` | describe |
+| `l` | controller logs | **Storage (`6`)** | |
+| `ctrl-d` | tear down | `ctrl-d` | delete bucket (and its objects) |
+| `e` / `R` | edit / re-apply (rolling) | **Workspaces (`:ws`)** | |
+| | | `enter` | switch the active workspace |
+
+| Volumes (`5`) | | Form templates (`:templates`) | |
+|---|---|---|---|
+| `c` | create (form) | `enter` | new resource from the template |
+| `ctrl-d` | delete (and its data) | `c` | new template from a working example |
+| `d` / `y` | describe / YAML | `E` | edit in the vim editor (a built-in saves your copy) |
+| `e` / `E` | edit in form / as YAML | `D` | duplicate |
+| `R` | re-apply | `ctrl-d` | delete yours (a built-in it replaced comes back) |
+| `i` | import the server's YAML | `o` | show (and copy) the path |
+
+Managed jobs have a **Run in pool** field: set it to submit the job to a pool's warm workers instead of
+provisioning a cluster (`sky jobs launch --pool`). Since the pool isn't part of SkyPilot's task YAML, the spec file
+records it in a `# twisk: pool=<name>` header comment.
+
+Log views: `f` toggle follow, `w` toggle wrap, `s` save to `~/.twisk/logs/`, `esc` detach (the work keeps running).
+
+## Editing YAML (the escape hatch)
+
+The forms cover the common fields. For anything else — `file_mounts`, `config:` overrides, a custom
+`instance_type`, an extra `service` option — edit the YAML directly, without leaving twisk:
+
+- **An existing resource or spec:** select it and press `E` (works in clusters, jobs, services, pools, volumes and
+  the spec library). Resources created outside twisk are seeded from the YAML the server recorded.
+- **A resource you're about to create:** fill what you can in the form, then `ctrl-e` to continue in the editor.
+  Nothing is written until `:w`, so `:q!` leaves no trace.
+
+The editor is a vim inside the TUI (normal / insert / visual modes; no vim binary needed):
+
+| | |
+|---|---|
+| `:w` · `:wq` (`ZZ`) · `:q` · `:q!` (`ZQ`) | save · save & close · close (refuses with unsaved changes) · discard |
+| `:apply` or `ctrl-s` | save, then launch the cluster / submit the job / roll out the service / apply the volume or pool |
+| `i a I A o O`, `esc` | insert modes (`o`/`O` keep YAML indentation, one level deeper after `key:`), back to normal |
+| `h j k l w b e 0 ^ $ gg G`, `ctrl-d/u` | motions, with counts (`3j`, `2w`, `5G`) |
+| `d c y > <` + motion, `dd yy cc >> <<` | operators on a motion or on lines |
+| `x X D C s S J r p P ~` | the usual single-key edits |
+| `v`, `V` | visual / visual-line selection, then an operator |
+| `u`, `ctrl-r` | undo / redo (one step per change) |
+| `/pattern`, `n`, `N` · `:42` | search (regex) · go to line |
+
+The status line shows the mode, unsaved changes (`[+]`) and whether the YAML is valid as you type; invalid YAML is
+never written. Prefer your own editor? Set `editor: nvim` (or `editor: $EDITOR`) in `~/.twisk/config.yaml` and `E`
+will suspend twisk and open it instead.
+
+## Form templates
+
+Every create/edit form in twisk is generated from a **template**: a YAML file that lists the form's fields and a
+[Jinja2](https://jinja.palletsprojects.com/templates/) template that turns the field values into SkyPilot YAML.
+twisk ships one per kind (`cluster`, `job`, `service`, `pool`, `volume`); yours live in `~/.twisk/templates/`.
+
+```yaml
+# ~/.twisk/templates/gpu-box.yaml
+kind: cluster                     # cluster | job | service | pool | volume
+title: GPU dev box
+description: One node on our Kubernetes cluster, with our base image
+fields:
+  - {key: name, label: Cluster name, required: true}     # every template needs `name`
+  - key: gpu
+    label: GPU
+    type: select
+    options: [L4, A100, H100]
+    default: L4
+  - {key: gpus, label: GPUs, type: int, default: 1, min: 1, max: 8}
+  - {key: team, label: Team, pattern: "[a-z]+", help: lowercase team name}
+  - {key: env, label: Environment, type: kv, help: "KEY=value, one per line"}
+template: |
+  name: {{ name }}
+  resources:
+    infra: k8s
+    accelerators: {{ gpu }}:{{ gpus }}
+    cpus: {{ gpus * 8 }}+
+    memory: {{ gpus * 64 }}+
+    image_id: docker:ghcr.io/acme/base:latest
+    autostop: {idle_minutes: 120, down: true}
+  envs: {{ env | yaml }}
+  {% if team %}
+  config:
+    kubernetes:
+      pod_config: {metadata: {labels: {team: {{ team | yaml }}}}}
+  {% endif %}
+```
+
+With that file in place, `c` in the clusters view asks which form to use; pick *GPU dev box* and you get exactly
+those five fields, with the rendered YAML live next to them.
+
+**Fields**
+
+| | |
+|---|---|
+| `key` | variable name in the template (letters, digits, `_`) |
+| `type` | `text` · `area` (multi-line) · `int` · `float` · `bool` · `select` · `list` (comma-separated → list) · `kv` (`KEY=value` lines → mapping) |
+| `label`, `section`, `help`, `placeholder` | how it shows in the form (fields are grouped by `section`) |
+| `default`, `required` | starting value; required fields can't be left empty |
+| `options` | for `select`: `[a, b]` or `[{label: …, value: …}]` (a value of `""` means "leave it out") |
+| `min`, `max`, `pattern` | validation for numbers / text (`pattern` is a full-match regex; `help` is shown as the error) |
+| `suggest` | completions: a list, or `infra` · `accelerators` · `volumes` · `pools` (live from your server) |
+| `path` | where the field lives in the YAML (`resources.cpus`, alternatives as `a|b`). Lets twisk fill the form from YAML it didn't render (e.g. a cluster created with `sky launch`) and attach SkyPilot validation errors to the right field. `twisk.pool` stores a job's pool. |
+
+**Templates**
+
+- Field values are variables; empty optional fields are `none`. `{{ x | yaml }}` renders any value as YAML (strings
+  get quoted, `kv` fields become mappings), and keys whose value comes out null or empty are dropped — so optional
+  fields rarely need `{% if %}`.
+- The output is validated like any spec: SkyPilot rules (`cpus: 4+`, `A100:8`, Kubernetes can't stop clusters, …) are
+  checked as you type, and unknown SkyPilot keys (`file_mounts`, `config`, …) pass straight through.
+- Templates run in Jinja2's sandbox.
+
+**Managing them**
+
+- `:templates` in the TUI lists every template and whether it's built-in, yours, or yours overriding a built-in.
+  `enter` creates a resource from it, `c` starts a new template from a working example, `E` edits one in the vim
+  editor (it's validated on `:w`; editing a built-in saves your copy), `D` duplicates, `ctrl-d` deletes yours.
+- A file named after a kind (`~/.twisk/templates/cluster.yaml`) **replaces that built-in form**.
+  `twisk templates init` copies all the built-ins there as a starting point.
+- `twisk templates list` / `validate` / `path` from the shell.
+
+**Editing later.** Specs remember which template and values made them, so `e` reopens the same form filled in.
+Changes you made in the YAML editor in the meantime are kept: twisk does a three-way merge between the file, what
+the form rendered last time, and what it renders now — anything the form doesn't produce survives, and anything you
+change in the form wins.
+
+## Layout
+
+```
+  src/twisk/
+    specs/        typed specs ⇄ SkyPilot YAML, and the on-disk spec library
+    backend/      Backend protocol; skypilot.py (SDK, API-server mode) and fake.py (demo/tests)
+    templates/    form templates: model, engine (render/validate/merge), registry, builtin/*.yaml
+    tui/          Textual app: views.py (resource tables), screens/ (form, vim editor, …), widgets/
+    sandbox.py    k3s + SkyPilot API server sandbox
+    cli.py        `twisk`, `twisk sandbox …`, `twisk specs …`, `twisk templates …`
+  tests/          unit + Textual pilot tests (fake backend); `-m sandbox` for live checks
+  scripts/        capture_screenshots.py — regenerates docs/assets (README screenshots + GIF)
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest                    # unit + TUI tests (fake backend, ~1.5 min)
+uv run pytest -m sandbox         # live checks against a running `twisk sandbox`
+```
+
+### Screenshots and the demo GIF
+
+`scripts/capture_screenshots.py` drives the real TUI against the demo backend, exports Textual screenshots and
+renders them with Playwright + Pillow into `docs/assets/`. Rerun it after UI changes and look at the GIF before
+committing:
+
+```bash
+uv sync --group docs
+uv run playwright install chromium   # once
+uv run python scripts/capture_screenshots.py
+```