feat: first-time user DX — guided hints, friendly errors, "did you mean?"

  - Friendly error when no kubeconfig found: links to quickstart guide
    instead of scary "Internal error: Invalid kube-config file"
  - "Did you mean?" suggestions when commands are mistyped
    (e.g. `logs` → `services:logs`, `scale` → `ps:scale`)
  - Next steps hints after apps:create, deploy, and services:expose:on
    guiding users through the full create → deploy → access flow
  - Log streaming Ctrl+C hint on its own line for visibility
  - SECURITY.md: full security architecture (secrets, RBAC, local storage)
  - README: added DigitalOcean, services:connect/expose:on in quickstart
  - Release workflow: native ARM64 runner replaces slow QEMU build
  - Test resilience: tighter polling, join timeouts, monkeypatch env vars
  - Bump to v0.2.0

Author: amanjain

.github/workflows/release.yml

@@ -91,7 +91,7 @@ jobs:
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
 
-  # ── Native binaries (4 targets) ─────────────────────────────────
+  # ── Native binaries (5 targets) ─────────────────────────────────
 
   binaries:
     name: Binary — ${{ matrix.os }}-${{ matrix.arch }}
@@ -105,6 +105,10 @@ jobs:
             arch: amd64
             runner: ubuntu-latest
             asset: kuberoku-linux-amd64
+          - os: linux
+            arch: arm64
+            runner: ubuntu-24.04-arm
+            asset: kuberoku-linux-arm64
           - os: darwin
             arch: arm64
             runner: macos-latest
@@ -159,44 +163,11 @@ jobs:
           name: ${{ matrix.asset }}
           path: dist/${{ matrix.asset }}
 
-  # ── Linux ARM64 via QEMU ────────────────────────────────────────
-
-  binary-linux-arm64:
-    name: Binary — linux-arm64 (QEMU)
-    needs: gate
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
-
-      - name: Build in ARM64 container
-        run: |
-          docker run --rm --platform linux/arm64 \
-            -v "${{ github.workspace }}:/work" \
-            -w /work \
-            python:3.12-slim \
-            sh -c '
-              apt-get update && apt-get install -y --no-install-recommends binutils &&
-              pip install --upgrade pip &&
-              pip install . &&
-              pip install pyinstaller &&
-              pyinstaller kuberoku.spec &&
-              mv dist/kuberoku dist/kuberoku-linux-arm64
-            '
-
-      - name: Upload artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: kuberoku-linux-arm64
-          path: dist/kuberoku-linux-arm64
-
   # ── GitHub Release ──────────────────────────────────────────────
 
   release:
     name: Create GitHub Release
-    needs: [publish, binaries, binary-linux-arm64]
+    needs: [publish, binaries]
     runs-on: ubuntu-latest
     permissions:
       contents: write

README.md

@@ -39,13 +39,14 @@ Requires `kubectl` configured with a valid kubeconfig. The Python install requir
 
 ### Already have a cluster?
 
-Five commands from zero to a running app:
+From zero to a running app accessible on the internet:
 
 ```bash
 kuberoku apps:create myapi
 kuberoku deploy --app myapi --image nginx:1.27 --port 80/tcp
+kuberoku services:connect --app myapi                          # test locally
+kuberoku services:expose:on --app myapi web                    # get a public IP
 kuberoku config:set --app myapi GREETING=hello SECRET_KEY=abc123
-kuberoku ps:scale --app myapi web=3
 kuberoku services:logs --app myapi --tail
 ```
 
@@ -132,6 +133,7 @@ Then run the five commands above.
 | **AWS** | `eksctl create cluster --name dev` ([docs](https://eksctl.io)) |
 | **GCP** | `gcloud container clusters create dev` ([docs](https://cloud.google.com/kubernetes-engine/docs/deploy-app-cluster)) |
 | **Azure** | `az aks create -g dev -n dev` ([docs](https://learn.microsoft.com/en-us/azure/aks/learn/quick-kubernetes-deploy-cli)) |
+| **DigitalOcean** | `doctl kubernetes cluster create dev` ([docs](https://docs.digitalocean.com/products/kubernetes/getting-started/quickstart/)) |
 
 Kuberoku works on any conformant K8s cluster (1.33+). No special setup required.
 

SECURITY.md

@@ -16,19 +16,76 @@ Include:
 
 You'll receive a response within 72 hours.
 
-## Scope
+## Security architecture
 
-Kuberoku is a CLI/SDK that talks to the Kubernetes API. It does not run server-side components. Security concerns include:
+Kuberoku is a **client-side only** tool. There are no server-side components, no daemons, no webhooks, and no admission controllers installed on your cluster. The CLI talks directly to the Kubernetes API using your existing kubeconfig credentials.
 
-- Secret value leakage in CLI output, logs, or crash reports
-- Command injection via user-supplied app names, config values, or arguments
-- Unsafe handling of kubeconfig credentials
-- Dependency vulnerabilities
+### What is stored locally
 
-## What Kuberoku does NOT protect
+| Location | Contents |
+|---|---|
+| `~/.kube/config` | Standard kubeconfig (not managed by Kuberoku) |
+| `~/.kuberoku/config.yaml` | Cluster registry: context names, namespaces, resource prefixes. **No credentials or secrets.** |
+| `.kuberoku` (project dir) | Optional project marker with default app name. No secrets. |
 
-- Secrets at rest in K8s (cluster admin responsibility: EncryptionConfiguration)
-- RBAC enforcement within a namespace (K8s limitation)
-- Network-level encryption (cluster responsibility: mTLS, network policies)
+**That's it.** Kuberoku does not store credentials, tokens, secrets, or sensitive data on disk. It delegates all authentication to your kubeconfig and the Kubernetes client library.
 
-See `docs/NORTHSTAR.txt` Section 1 for the full security model.
+### How secrets are handled
+
+- **Config vars** set with `config:set --secret` are stored as [Kubernetes Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) using `stringData` (not base64-encoded `data`).
+- Secrets are **never written to local disk**, logs, or crash reports.
+- Secret values are **masked in CLI output** — only key names are shown.
+- Addon credentials (database passwords, etc.) are stored in K8s Secrets and injected into pods via environment variables.
+- **Secrets at rest encryption** is your cluster's responsibility (`EncryptionConfiguration`). Kuberoku uses whatever protection your cluster provides.
+
+### Network posture
+
+- **Outbound only**: CLI → Kubernetes API server (HTTPS). No inbound connections.
+- No telemetry, analytics, or phone-home behavior.
+- Plugin install/search talks to PyPI (HTTPS) — only when explicitly invoked.
+
+### RBAC permissions
+
+Kuberoku follows least-privilege. Run `kuberoku clusters:doctor` to audit your permissions, or `clusters:doctor --fix` to generate minimal Role/RoleBinding YAML.
+
+**Required** (core functionality):
+
+| Resource | API Group | Verbs | Used by |
+|---|---|---|---|
+| namespaces | core | get, list | apps |
+| configmaps | core | get, list, create, update, patch, delete | apps, config, releases |
+| deployments | apps | get, list, create, update, patch, delete | deploy, ps |
+| pods | core | get, list, delete | ps, restart |
+| pods/log | core | get | logs |
+| pods/exec | core | create | exec |
+| services | core | get, list, create, update, delete | deploy, addons |
+| jobs | batch | get, list, create, delete | run |
+
+**Elevated** (optional features — only needed if you use them):
+
+| Resource | API Group | Verbs | Used by |
+|---|---|---|---|
+| secrets | core | get, list, create, update, patch, delete | config --secret |
+| ingresses | networking.k8s.io | get, list, create, update, delete | domains |
+| statefulsets | apps | get, list, create, update, patch, delete | addons |
+| persistentvolumeclaims | core | get, list, create, delete | addons |
+| networkpolicies | networking.k8s.io | get, list, create, update, delete | networking |
+
+### Scope of responsibility
+
+| Kuberoku handles | Cluster admin handles |
+|---|---|
+| Safe CLI input validation | Secrets at rest encryption (`EncryptionConfiguration`) |
+| No secrets in logs/output | RBAC enforcement between namespaces |
+| Namespace isolation of resources | Network-level encryption (mTLS) |
+| Minimal RBAC requirements | Cluster authentication (OIDC, certificates) |
+
+### Dependencies
+
+Kuberoku has 3 runtime dependencies, minimizing supply chain surface:
+
+- `kubernetes` — official Kubernetes Python client
+- `click` — CLI framework
+- `pyyaml` — YAML parsing
+
+All PyPI releases use [OIDC trusted publishing](https://docs.pypi.org/trusted-publishers/) (no long-lived API tokens).

src/kuberoku/_version.py

@@ -1 +1 @@
-__version__ = "0.1.0"
+__version__ = "0.2.0"

src/kuberoku/cli/apps.py

@@ -7,7 +7,7 @@
 import click
 
 from kuberoku.cli.context import resolve_app
-from kuberoku.cli.output import info, render_detail, render_table, success
+from kuberoku.cli.output import hint, info, render_detail, render_table, success
 from kuberoku.config.project import (
     remove_alias,
     remove_project_file,
@@ -58,6 +58,10 @@ def create(ctx: click.Context, name: str, cluster: str | None) -> None:
     factory = ctx.obj["factory"]
     app = factory.apps.create(name, on_step=lambda msg: info(msg))
     success(f"Created app {app.name}.")
+    hint("\nNext steps:")
+    hint(f"  kuberoku deploy --app {app.name} --image <your-image> --port 80/tcp")
+    hint(f"  kuberoku config:set --app {app.name} KEY=value")
+    hint(f"  kuberoku apps:info --app {app.name}")
 
 
 @apps.command()

src/kuberoku/cli/deploy.py

@@ -7,7 +7,7 @@
 import click
 
 from kuberoku.cli.context import resolve_app
-from kuberoku.cli.output import info, render_detail, success
+from kuberoku.cli.output import hint, info, render_detail, success
 from kuberoku.sdk.deploy import parse_port
 
 
@@ -75,3 +75,7 @@ def deploy(
             "Processes": ", ".join(release.images.keys()),
         },
     )
+    hint("\nNext steps:")
+    hint(f"  kuberoku services:connect --app {app_name}         # access locally")
+    hint(f"  kuberoku services:expose:on --app {app_name} web   # expose to internet")
+    hint(f"  kuberoku services:logs --app {app_name} --tail")

src/kuberoku/cli/main.py

@@ -29,6 +29,10 @@ class ColonCommandGroup(click.Group):
     Both `kuberoku apps:create` and `kuberoku apps create` work identically.
     This overrides resolve_command() — Click's intended extension point for
     custom command resolution.
+
+    When a bare command name isn't found (e.g. ``logs``), searches all
+    registered groups for a matching subcommand and suggests the full
+    colon syntax (e.g. ``services:logs``).
     """
 
     def resolve_command(
@@ -39,7 +43,26 @@ def resolve_command(
         if cmd_name and ":" in cmd_name:
             parts = cmd_name.split(":", 1)
             args = [parts[0], parts[1]] + args[1:]
-        return super().resolve_command(ctx, args)
+        try:
+            return super().resolve_command(ctx, args)
+        except click.UsageError:
+            # Command not found — search subgroups for a match
+            if cmd_name and ":" not in cmd_name:
+                suggestions = self._find_in_groups(cmd_name)
+                if suggestions:
+                    hint = ", ".join(f"'{s}'" for s in suggestions)
+                    raise click.UsageError(
+                        f"No such command '{cmd_name}'. Did you mean {hint}?"
+                    ) from None
+            raise
+
+    def _find_in_groups(self, name: str) -> list[str]:
+        """Search all registered groups for a subcommand matching name."""
+        matches: list[str] = []
+        for group_name, cmd in (self.commands or {}).items():
+            if isinstance(cmd, click.Group) and cmd.get_command(None, name):  # type: ignore[arg-type]
+                matches.append(f"{group_name}:{name}")
+        return matches
 
 
 @click.group(cls=ColonCommandGroup)

src/kuberoku/cli/output.py

@@ -35,6 +35,11 @@ def info(message: str) -> None:
     click.echo(message)
 
 
+def hint(message: str) -> None:
+    """Print a hint/next-step message."""
+    click.echo(message, err=True)
+
+
 def render_table(
     items: list[Any],
     columns: list[str],

src/kuberoku/cli/services.py

@@ -9,7 +9,7 @@
 import click
 
 from kuberoku.cli.context import resolve_app
-from kuberoku.cli.output import info, render_detail, success
+from kuberoku.cli.output import hint, info, render_detail, success
 from kuberoku.models import LogLine
 
 
@@ -125,6 +125,8 @@ def expose_on(
     if endpoint.ports:
         fields["Ports"] = ", ".join(str(p) for p in endpoint.ports)
     render_detail(f"{app_name} expose", fields)
+    hint("\nMap a custom domain:")
+    hint(f"  kuberoku domains:add --app {app_name} myapp.example.com")
 
 
 @expose.command("off")
@@ -341,7 +343,8 @@ def on_line(line: LogLine) -> None:
             ts_prefix = f"{line.timestamp.isoformat()} " if timestamps else ""
             click.echo(f"{ts_prefix}{line.dyno} | {line.message}")
 
-        info(f"Streaming logs for app '{app_name}'... (Ctrl+C to stop)")
+        info(f"Streaming logs for app '{app_name}'...")
+        info("Press Ctrl+C to stop.\n")
         try:
             factory.services.stream_logs(
                 app_name,

src/kuberoku/exceptions.py

@@ -136,6 +136,24 @@ class ClusterUnreachableError(KuberokuError):
     """Raised when the K8s API server can't be reached."""
 
 
+class NoKubeConfigError(KuberokuError):
+    """Raised when no kubeconfig file is found (first-time user)."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "No Kubernetes cluster connected.\n"
+            "\n"
+            "Kuberoku needs a Kubernetes cluster to run your apps.\n"
+            "New to Kubernetes? Follow the quickstart guide:\n"
+            "\n"
+            "  https://github.com/amanjain/kuberoku#need-a-cluster-first\n"
+            "\n"
+            "Already have a cluster? Make sure kubectl can reach it:\n"
+            "\n"
+            "  kubectl cluster-info"
+        )
+
+
 class NoCurrentClusterError(KuberokuError):
     """Raised when no current cluster is set and none can be inferred."""