docs: update README to enhance clarity on functionality and commands

README.md

@@ -1,15 +1,152 @@
 # kuber
 
-To install dependencies:
+`kuber` is Astral's internal Docker Compose to Kubernetes translation layer.
+
+It reads a local Compose file, renders Kubernetes resources, applies them to the cluster, and can build images remotely from your working tree without requiring Docker on your machine.
+
+## What It Does
+
+- Reads `compose.yml` or `docker-compose.yml`
+- Converts supported Compose services into Kubernetes resources
+- Applies those resources into a namespace named after the current directory
+- Turns `env_file` entries into Kubernetes Secrets and mounts them through `envFrom`
+- Translates file mounts into ConfigMaps and directory/volume mounts into PVC-backed volumes
+- Builds images on the remote builder by syncing:
+    - committed git state
+    - tracked local diffs
+    - untracked files
+    - ignored `.env*` files
+- Supports host-based `ports` syntax that renders Kubernetes `Ingress` rules
+- Supports managed Postgres claims through special pseudo-volumes such as `postgresql:app`
+
+## Environment Assumptions
+
+This tool is built for Astral's cluster and workstation setup. It is not intended to work unchanged outside that environment.
+
+Expected local setup:
+
+- Tailscale access to the remote builder and Kubernetes network
+- a working `~/.kube/config`
+- `ssh` available locally
+
+Not required locally:
+
+- Docker
+- `kubectl`
+
+Docker is not required because builds happen on the remote builder after `kuber` syncs your repo state there. `kubectl` is not required because cluster access is handled through the bundled Kubernetes client.
+
+## Running
+
+During development:
 
 ```bash
-bun install
+bun run index.ts up
 ```
 
-To run:
+Other useful commands:
 
 ```bash
-bun run index.ts
+bun run index.ts ps
+bun run index.ts logs
+bun run index.ts logs -f
+bun run index.ts exec app sh
+bun run index.ts start
+bun run index.ts stop
+bun run index.ts restart
+bun run index.ts db ls
 ```
 
-This project was created using `bun init` in bun v1.3.13. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+## Commands
+
+- `up`: build images if needed, render manifests, apply them, restart deployments, and wait for rollout
+- `start`: same as `up` but skips image builds
+- `stop`: scale managed deployments to zero
+- `restart`: roll out a restart across managed deployments
+- `down`: delete managed resources while keeping ingress, PVCs, and managed databases
+- `down -f`: also delete ingress, PVCs, managed database resources, and the namespace
+- `ps`: list deployments in the current project namespace
+- `logs [deployment]`: print logs for one deployment or all managed deployments
+- `logs -f [deployment]`: follow logs continuously
+- `exec <deployment> <command...>`: execute a command inside a running deployment pod
+- `db ls`: list managed Postgres claims declared in the current Compose file
+- `db creds <service>`: print the generated connection details for a managed Postgres claim
+
+## Compose Conventions
+
+`kuber` supports a few project-specific Compose conventions on top of normal service translation.
+
+### Host-Based Ports
+
+If a `ports` entry uses a hostname instead of a numeric published port, `kuber` treats it as an ingress host and routes traffic to the target container port.
+
+Example:
+
+```yml
+services:
+  app:
+    ports:
+      - somedomain.astrxl.dev:3000
+```
+
+That produces a Kubernetes `Ingress` rule for `somedomain.astrxl.dev` pointing at the service port for container port `3000`.
+
+### Managed Postgres
+
+You can declare a managed Postgres database with a pseudo-volume:
+
+```yml
+services:
+  app:
+    volumes:
+      - postgresql:app
+```
+
+Or with an explicit username and database name:
+
+```yml
+services:
+  app:
+    volumes:
+      - postgresql:user/database
+```
+
+This creates or reuses the managed CNPG role secret, reconciles the database resource, and injects `DATABASE_URL` into the generated app secret in Kubernetes.
+
+### Environment Files
+
+`env_file` entries are read locally and turned into a Kubernetes `Secret` named `<service>-env`. Deployments then consume that secret through `envFrom`.
+
+This is also where generated values such as `DATABASE_URL` are injected.
+
+### Volumes
+
+`kuber` treats different volume shapes differently:
+
+- file bind mounts become ConfigMaps
+- directory bind mounts become PVC-backed mounts
+- named volumes become PVC-backed mounts
+- `tmpfs` becomes `emptyDir` with memory backing
+- `postgresql:...` is treated as a managed database claim, not as a filesystem mount
+
+## Building
+
+To build distributable binaries:
+
+```bash
+bun run build.ts
+```
+
+If you only want a plain JavaScript bundle for quick local use in another workspace, build `index.ts` directly:
+
+```bash
+bun build index.ts --target bun --minify --sourcemap --outdir dist
+```
+
+## Notes
+
+- Resource names and namespaces are derived from the current working directory.
+- The remote build flow is optimized for local iteration, not for producing a perfectly clean export of the repository.
+- Managed database support is Kubernetes-only. It injects `DATABASE_URL` into the generated app secret and does not rewrite local `.env` files.
+- `kuber` operates on managed resources in the namespace matching the current directory name.
+