@revos/cli 0.2.3 → 0.3.1

package/dist/{index-D0ax2I61.d.mts → index-Cbb9pLt6.d.mts}

@@ -25,6 +25,7 @@ declare class ApiError extends Error {
 //#endregion
 //#region src/core/config.d.ts
 declare const DEFAULT_API_URL = "https://api.revos.ai";
+declare function resolveApiUrl(): string;
 declare function getConfig(): Promise<Config>;
 //#endregion
 //#region src/core/auth/credentials-store.d.ts
@@ -78,6 +79,18 @@ declare function getUserInfo(accessToken: string): Promise<ClerkUserInfo>;
 declare function tokenResponseToCredentials(tokenResponse: TokenResponse, userInfo: ClerkUserInfo): StoredCredentials;
 declare function refreshAccessToken(refreshToken: string): Promise<TokenResponse>;
 //#endregion
+//#region src/core/auth/oauth-flow.d.ts
+interface PerformOAuthLoginOptions {
+  apiUrl: string;
+  organizationId?: string;
+  log?: (msg: string) => void;
+}
+interface PerformOAuthLoginResult {
+  credentials: StoredCredentials;
+  userInfo: ClerkUserInfo;
+}
+declare function performOAuthLogin(opts: PerformOAuthLoginOptions): Promise<PerformOAuthLoginResult>;
+//#endregion
 //#region src/core/utils.d.ts
 declare function formatError(error: unknown): string;
 declare function sanitizeFileName(name: string): string;
@@ -559,6 +572,16 @@ interface InitResult {
   createdFiles: string[];
   pulledIac: PullResult;
 }
+interface EnsureGcpKeyOptions {
+  apiUrl: string;
+  token: string;
+  organization: OrganizationInfo;
+  projectSlug: string;
+}
+interface EnsureGcpKeyResult {
+  keyPath: string;
+  status: "exists" | "created";
+}
 declare class InitService {
   private readonly templatesDir;
   private static readonly PROJECT_DIRS;
@@ -567,6 +590,8 @@ declare class InitService {
   run(options: InitOptions): Promise<InitResult>;
   private pullIacResources;
   resolveOrganization(apiUrl: string, token: string, organizationId?: string): Promise<OrganizationInfo>;
+  static gcpKeyPath(projectSlug: string): string;
+  ensureGcpKey(options: EnsureGcpKeyOptions): Promise<EnsureGcpKeyResult>;
   private downloadGcpKey;
   dryRun(projectDir: string): {
     projectDir: string;
@@ -578,4 +603,4 @@ declare class InitService {
   private renderTemplate;
 }
 //#endregion
-export { setAuthEnv as A, getConfig as B, buildAuthorizationUrl as C, getUserInfo as D, getActiveAuthConfig as E, getCredentialsPath as F, Config as H, isTokenExpired as I, loadCredentials as L, OAuthServerResult as M, startOAuthServer as N, refreshAccessToken as O, deleteCredentials as P, saveCredentials as R, PKCEChallenge as S, generatePKCEChallenge as T, ApiError as V, formatError as _, formatEnvMismatchError as a, AuthConfig as b, renderProjectContextLine as c, PulledResource as d, AppliedResource as f, resolveAppUrl as g, unwrap as h, formatCredentialsMismatchWarning as i, tokenResponseToCredentials as j, setAuthConfig as k, index_d_exports as l, createApiClient as m, InitResult as n, formatInProjectSwitchWarning as o, ApiClient as p, InitService as r, formatProjectOrgFlagError as s, InitOptions as t, ResourceStatus as u, sanitizeFileName as v, exchangeCodeForTokens as w, AuthEnv as x, AUTH_ENVS as y, DEFAULT_API_URL as z };
+export { getUserInfo as A, loadCredentials as B, AuthConfig as C, exchangeCodeForTokens as D, buildAuthorizationUrl as E, OAuthServerResult as F, ApiError as G, DEFAULT_API_URL as H, startOAuthServer as I, Config as K, deleteCredentials as L, setAuthConfig as M, setAuthEnv as N, generatePKCEChallenge as O, tokenResponseToCredentials as P, getCredentialsPath as R, AUTH_ENVS as S, PKCEChallenge as T, getConfig as U, saveCredentials as V, resolveApiUrl as W, formatError as _, formatEnvMismatchError as a, PerformOAuthLoginResult as b, renderProjectContextLine as c, PulledResource as d, AppliedResource as f, resolveAppUrl as g, unwrap as h, formatCredentialsMismatchWarning as i, refreshAccessToken as j, getActiveAuthConfig as k, index_d_exports as l, createApiClient as m, InitResult as n, formatInProjectSwitchWarning as o, ApiClient as p, InitService as r, formatProjectOrgFlagError as s, InitOptions as t, ResourceStatus as u, sanitizeFileName as v, AuthEnv as w, performOAuthLogin as x, PerformOAuthLoginOptions as y, isTokenExpired as z };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { A as setAuthEnv, B as getConfig, C as buildAuthorizationUrl, D as getUserInfo, E as getActiveAuthConfig, F as getCredentialsPath, H as Config, I as isTokenExpired, L as loadCredentials, M as OAuthServerResult, N as startOAuthServer, O as refreshAccessToken, P as deleteCredentials, R as saveCredentials, S as PKCEChallenge, T as generatePKCEChallenge, V as ApiError, _ as formatError, a as formatEnvMismatchError, b as AuthConfig, c as renderProjectContextLine, g as resolveAppUrl, h as unwrap, i as formatCredentialsMismatchWarning, j as tokenResponseToCredentials, k as setAuthConfig, l as index_d_exports, m as createApiClient, n as InitResult, o as formatInProjectSwitchWarning, p as ApiClient, r as InitService, s as formatProjectOrgFlagError, t as InitOptions, v as sanitizeFileName, w as exchangeCodeForTokens, x as AuthEnv, y as AUTH_ENVS, z as DEFAULT_API_URL } from "./index-D0ax2I61.mjs";
+import { A as getUserInfo, B as loadCredentials, C as AuthConfig, D as exchangeCodeForTokens, E as buildAuthorizationUrl, F as OAuthServerResult, G as ApiError, H as DEFAULT_API_URL, I as startOAuthServer, K as Config, L as deleteCredentials, M as setAuthConfig, N as setAuthEnv, O as generatePKCEChallenge, P as tokenResponseToCredentials, R as getCredentialsPath, S as AUTH_ENVS, T as PKCEChallenge, U as getConfig, V as saveCredentials, W as resolveApiUrl, _ as formatError, a as formatEnvMismatchError, b as PerformOAuthLoginResult, c as renderProjectContextLine, g as resolveAppUrl, h as unwrap, i as formatCredentialsMismatchWarning, j as refreshAccessToken, k as getActiveAuthConfig, l as index_d_exports, m as createApiClient, n as InitResult, o as formatInProjectSwitchWarning, p as ApiClient, r as InitService, s as formatProjectOrgFlagError, t as InitOptions, v as sanitizeFileName, w as AuthEnv, x as performOAuthLogin, y as PerformOAuthLoginOptions, z as isTokenExpired } from "./index-Cbb9pLt6.mjs";
 import { a as OrgListResult, c as StoredCredentials, i as OAuthCallbackResult, l as TokenResponse, n as AuthStatusInfo, o as OrgSwitchResult, r as ClerkUserInfo, s as OrganizationInfo, t as AuthResult } from "./types-Bk2Cb5yt.mjs";
 import { a as validateEnvAgainstProject, i as resolveProjectContext, n as ProjectContext, r as isInsideProject, t as EnvMismatch } from "./context-D5uelKLe.mjs";
-export { AUTH_ENVS, ApiClient, ApiError, AuthConfig, AuthEnv, AuthResult, AuthStatusInfo, ClerkUserInfo, Config, DEFAULT_API_URL, EnvMismatch, InitOptions, InitResult, InitService, OAuthCallbackResult, OAuthServerResult, OrgListResult, OrgSwitchResult, OrganizationInfo, PKCEChallenge, ProjectContext, StoredCredentials, TokenResponse, buildAuthorizationUrl, createApiClient, deleteCredentials, exchangeCodeForTokens, formatCredentialsMismatchWarning, formatEnvMismatchError, formatError, formatInProjectSwitchWarning, formatProjectOrgFlagError, generatePKCEChallenge, getActiveAuthConfig, getConfig, getCredentialsPath, getUserInfo, index_d_exports as iac, isInsideProject, isTokenExpired, loadCredentials, refreshAccessToken, renderProjectContextLine, resolveAppUrl, resolveProjectContext, sanitizeFileName, saveCredentials, setAuthConfig, setAuthEnv, startOAuthServer, tokenResponseToCredentials, unwrap, validateEnvAgainstProject };
+export { AUTH_ENVS, ApiClient, ApiError, AuthConfig, AuthEnv, AuthResult, AuthStatusInfo, ClerkUserInfo, Config, DEFAULT_API_URL, EnvMismatch, InitOptions, InitResult, InitService, OAuthCallbackResult, OAuthServerResult, OrgListResult, OrgSwitchResult, OrganizationInfo, PKCEChallenge, PerformOAuthLoginOptions, PerformOAuthLoginResult, ProjectContext, StoredCredentials, TokenResponse, buildAuthorizationUrl, createApiClient, deleteCredentials, exchangeCodeForTokens, formatCredentialsMismatchWarning, formatEnvMismatchError, formatError, formatInProjectSwitchWarning, formatProjectOrgFlagError, generatePKCEChallenge, getActiveAuthConfig, getConfig, getCredentialsPath, getUserInfo, index_d_exports as iac, isInsideProject, isTokenExpired, loadCredentials, performOAuthLogin, refreshAccessToken, renderProjectContextLine, resolveApiUrl, resolveAppUrl, resolveProjectContext, sanitizeFileName, saveCredentials, setAuthConfig, setAuthEnv, startOAuthServer, tokenResponseToCredentials, unwrap, validateEnvAgainstProject };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { A as generatePKCEChallenge, B as isTokenExpired, C as formatError, D as AUTH_ENVS, E as getConfig, F as setAuthEnv, H as saveCredentials, I as tokenResponseToCredentials, L as startOAuthServer, M as getUserInfo, N as refreshAccessToken, O as buildAuthorizationUrl, P as setAuthConfig, R as deleteCredentials, S as resolveAppUrl, T as DEFAULT_API_URL, U as ApiError, V as loadCredentials, a as formatInProjectSwitchWarning, b as createApiClient, c as isInsideProject, d as iac_exports, i as formatEnvMismatchError, j as getActiveAuthConfig, k as exchangeCodeForTokens, l as resolveProjectContext, o as formatProjectOrgFlagError, r as formatCredentialsMismatchWarning, s as renderProjectContextLine, t as InitService, u as validateEnvAgainstProject, w as sanitizeFileName, x as unwrap, z as getCredentialsPath } from "./core-B-IdeRNl.mjs";
-export { AUTH_ENVS, ApiError, DEFAULT_API_URL, InitService, buildAuthorizationUrl, createApiClient, deleteCredentials, exchangeCodeForTokens, formatCredentialsMismatchWarning, formatEnvMismatchError, formatError, formatInProjectSwitchWarning, formatProjectOrgFlagError, generatePKCEChallenge, getActiveAuthConfig, getConfig, getCredentialsPath, getUserInfo, iac_exports as iac, isInsideProject, isTokenExpired, loadCredentials, refreshAccessToken, renderProjectContextLine, resolveAppUrl, resolveProjectContext, sanitizeFileName, saveCredentials, setAuthConfig, setAuthEnv, startOAuthServer, tokenResponseToCredentials, unwrap, validateEnvAgainstProject };
+import { A as buildAuthorizationUrl, B as deleteCredentials, C as formatError, D as resolveApiUrl, E as getConfig, F as refreshAccessToken, G as ApiError, H as isTokenExpired, I as setAuthConfig, L as setAuthEnv, M as generatePKCEChallenge, N as getActiveAuthConfig, O as performOAuthLogin, P as getUserInfo, R as tokenResponseToCredentials, S as resolveAppUrl, T as DEFAULT_API_URL, U as loadCredentials, V as getCredentialsPath, W as saveCredentials, a as formatInProjectSwitchWarning, b as createApiClient, c as isInsideProject, d as iac_exports, i as formatEnvMismatchError, j as exchangeCodeForTokens, k as AUTH_ENVS, l as resolveProjectContext, o as formatProjectOrgFlagError, r as formatCredentialsMismatchWarning, s as renderProjectContextLine, t as InitService, u as validateEnvAgainstProject, w as sanitizeFileName, x as unwrap, z as startOAuthServer } from "./core-CY9pC37x.mjs";
+export { AUTH_ENVS, ApiError, DEFAULT_API_URL, InitService, buildAuthorizationUrl, createApiClient, deleteCredentials, exchangeCodeForTokens, formatCredentialsMismatchWarning, formatEnvMismatchError, formatError, formatInProjectSwitchWarning, formatProjectOrgFlagError, generatePKCEChallenge, getActiveAuthConfig, getConfig, getCredentialsPath, getUserInfo, iac_exports as iac, isInsideProject, isTokenExpired, loadCredentials, performOAuthLogin, refreshAccessToken, renderProjectContextLine, resolveApiUrl, resolveAppUrl, resolveProjectContext, sanitizeFileName, saveCredentials, setAuthConfig, setAuthEnv, startOAuthServer, tokenResponseToCredentials, unwrap, validateEnvAgainstProject };

package/dist/{presets-Bb9gwgeh.mjs → presets-mJzFGMhG.mjs}

@@ -1,5 +1,5 @@
-import { x as unwrap } from "./core-B-IdeRNl.mjs";
-import { n as createListRender, r as defineApiCommand, t as bodyFlag } from "./factory-CCcimDhl.mjs";
+import { x as unwrap } from "./core-CY9pC37x.mjs";
+import { n as createListRender, r as defineApiCommand, t as bodyFlag } from "./factory-DTqayaCF.mjs";
 import { Args, Flags } from "@oclif/core";
 //#region src/adapters/oclif/presets.ts
 function camelToKebab(s) {

package/dist/templates/.devcontainer/Dockerfile

@@ -1,5 +1,13 @@
 FROM mcr.microsoft.com/devcontainers/python:3.13
 
+# jq is used by .devcontainer/welcome.sh + post-start.sh to parse
+# `revos auth status --json`.
+# It usually ships in the base image via common-debian.sh, but install
+# explicitly so this gate doesn't silently break on a future base bump.
+RUN apt-get update -q \
+    && apt-get install -y --no-install-recommends jq \
+    && rm -rf /var/lib/apt/lists/*
+
 # Pre-install dbt so it's available before VS Code extensions activate
 # (cryptography<47 avoids Illegal instruction on ARM)
 RUN pip install --quiet dbt-bigquery "cryptography<47"

package/dist/templates/.devcontainer/devcontainer.json

@@ -14,25 +14,26 @@
   },
   "containerEnv": {
     "DBT_PROJECT_DIR": "${containerWorkspaceFolder}/dbt",
-    "GOOGLE_APPLICATION_CREDENTIALS": "/home/vscode/.revos/gsa-creds.json",
+    "GOOGLE_APPLICATION_CREDENTIALS": "/home/vscode/.revos/<%=projectSlug%>-gsa-creds.json",
     "GOOGLE_CLOUD_PROJECT": "<%=bqProjectId%>",
     "REVOS_BQ_DATASET": "<%=bqDataset%>",
     "REVOS_ORG_ID": "<%=organizationId%>"
   },
-  "postCreateCommand": "bash .devcontainer/setup.sh",
+  "postCreateCommand": "bash .devcontainer/post-create.sh",
+  "postStartCommand": "bash .devcontainer/post-start.sh",
   "mounts": [
     {
-      "source": "${localEnv:HOME}${localEnv:USERPROFILE}/.revos/<%=projectSlug%>-gsa-creds.json",
-      "target": "/tmp/.revos-gsa-creds.json",
-      "type": "bind"
+      "source": "revos-<%=projectSlug%>-credentials",
+      "target": "/home/vscode/.revos",
+      "type": "volume"
     },
     {
-      "source": "${localEnv:HOME}${localEnv:USERPROFILE}/.revos/credentials.json",
-      "target": "/tmp/.revos-credentials.json",
-      "type": "bind"
+      "source": "revos-<%=projectSlug%>-gcloud",
+      "target": "/home/vscode/.config/gcloud",
+      "type": "volume"
     },
     {
-      "source": "claude-code-config",
+      "source": "revos-<%=projectSlug%>-claude",
       "target": "/home/vscode/.claude",
       "type": "volume"
     }

package/dist/templates/.devcontainer/post-create.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Named volumes mount as root-owned by default. We use three per-project
+# volumes (~/.revos, ~/.config/gcloud, ~/.claude) instead of one whole-home
+# volume because VS Code's server install writes to ~/.vscode-server before
+# postCreateCommand runs, and there's no clean lifecycle hook to fix
+# ownership early enough for a whole-home mount.
+sudo chown -R vscode:vscode /home/vscode/.revos 2>/dev/null || true
+sudo chown -R vscode:vscode /home/vscode/.config/gcloud 2>/dev/null || true
+sudo chown -R vscode:vscode /home/vscode/.claude 2>/dev/null || true
+mkdir -p "$HOME/.revos" "$HOME/.config/gcloud"
+
+# Install RevOS CLI
+npm install -g @revos/cli
+
+# Best-effort gcloud activation. Usually a no-op on first container create
+# (user hasn't run `revos init` yet, no key file), but covers the case
+# where the credentials volume was preserved across a recreate. After this,
+# the gcloud auth state lives in the persisted ~/.config/gcloud volume, so
+# subsequent rebuilds don't need re-activation. `revos init` itself also
+# activates when it provisions a new key.
+KEY="${GOOGLE_APPLICATION_CREDENTIALS:-}"
+if [ -n "$KEY" ] && [ -s "$KEY" ]; then
+  gcloud auth activate-service-account --key-file="$KEY" >/dev/null 2>&1 || true
+  if [ -n "${GOOGLE_CLOUD_PROJECT:-}" ]; then
+    gcloud config set project "$GOOGLE_CLOUD_PROJECT" >/dev/null 2>&1 || true
+  fi
+fi
+
+# Symlink dbt profiles so `dbt run` works without --profiles-dir
+mkdir -p "$HOME/.dbt"
+ln -sf "$(pwd)/dbt/profiles.yml" "$HOME/.dbt/profiles.yml"
+
+# Install the onboarding-banner welcome check. We copy it into ~/.revos so
+# it survives outside the workspace mount, and source it from ~/.bashrc so
+# it prints at the top of every interactive terminal — instead of being
+# buried under postStartCommand logs in the "Dev Containers" output panel.
+# The script self-clears once auth + key exist.
+cp .devcontainer/welcome.sh "$HOME/.revos/welcome.sh"
+
+if ! grep -qF 'source ~/.revos/welcome.sh' "$HOME/.bashrc" 2>/dev/null; then
+  echo '' >> "$HOME/.bashrc"
+  echo '# RevOS dev-container onboarding banner (auto-clears once set up)' >> "$HOME/.bashrc"
+  echo 'source ~/.revos/welcome.sh' >> "$HOME/.bashrc"
+fi

package/dist/templates/.devcontainer/post-start.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Runs on every container start (postStartCommand). Pure information —
+# either SETUP REQUIRED (with next steps) or READY (with environment debug
+# info). Important for users who open Claude Code directly and never touch
+# a terminal where welcome.sh would otherwise print the gate.
+#
+# gcloud activation lives in post-create.sh (one-time) and inside `revos
+# init` (when a new key is provisioned). The persisted ~/.config/gcloud
+# named volume keeps the activation state across rebuilds, so this script
+# doesn't need to re-activate on every start.
+
+need_setup=false
+
+if command -v revos >/dev/null 2>&1; then
+  if ! revos auth status --json 2>/dev/null | jq -e '.authenticated' >/dev/null 2>&1; then
+    need_setup=true
+  fi
+  if [ ! -s "$HOME/.revos/<%=projectSlug%>-gsa-creds.json" ]; then
+    need_setup=true
+  fi
+fi
+
+if $need_setup; then
+  echo ""
+  echo "████████████████████████████████████████████████████████████████████████"
+  echo "█                                                                      █"
+  echo "█   ⚠  REVOS DEV CONTAINER — SETUP REQUIRED                            █"
+  echo "█                                                                      █"
+  echo "█   Open a terminal and run:                                           █"
+  echo "█                                                                      █"
+  echo "█       revos init                                                     █"
+  echo "█                                                                      █"
+  echo "████████████████████████████████████████████████████████████████████████"
+  echo ""
+else
+  # Setup is complete — print a confirmation banner with environment debug
+  # info. Useful for users who never open a terminal, and as a quick
+  # reference when troubleshooting "is my container looking at the right
+  # project / dataset / org?".
+  user_email=$(revos auth status --json 2>/dev/null | jq -r '.email // "(unknown)"')
+  gcloud_account=$(gcloud config get-value account 2>/dev/null || true)
+  gcloud_account=${gcloud_account:-(none)}
+  gcloud_project=$(gcloud config get-value project 2>/dev/null || true)
+  gcloud_project=${gcloud_project:-${GOOGLE_CLOUD_PROJECT:-(none)}}
+
+  echo ""
+  echo "████████████████████████████████████████████████████████████████████████"
+  echo "█                                                                      █"
+  echo "█   ✓  REVOS DEV CONTAINER — READY                                     █"
+  echo "█                                                                      █"
+  printf "█   RevOS user:    %-51s █\n" "${user_email:0:51}"
+  printf "█   GCP account:   %-51s █\n" "${gcloud_account:0:51}"
+  printf "█   GCP project:   %-51s █\n" "${gcloud_project:0:51}"
+  printf "█   BQ dataset:    %-51s █\n" "${REVOS_BQ_DATASET:-(unset)}"
+  printf "█   Org ID:        %-51s █\n" "${REVOS_ORG_ID:-(unset)}"
+  echo "█                                                                      █"
+  echo "████████████████████████████████████████████████████████████████████████"
+  echo ""
+fi

package/dist/templates/.devcontainer/welcome.sh

@@ -0,0 +1,26 @@
+# RevOS dev-container welcome check. Sourced from ~/.bashrc on every
+# interactive shell. Silent once `revos auth status` is authenticated and
+# the GSA key file is present. `revos init` handles both — it signs you in
+# via the browser if needed, then provisions the GSA key.
+__revos_need_setup=false
+
+if ! command -v revos >/dev/null 2>&1; then
+  return 0
+fi
+if ! revos auth status --json 2>/dev/null | jq -e '.authenticated' >/dev/null 2>&1; then
+  __revos_need_setup=true
+fi
+if [ ! -s "$HOME/.revos/<%=projectSlug%>-gsa-creds.json" ]; then
+  __revos_need_setup=true
+fi
+
+if $__revos_need_setup; then
+  echo ""
+  echo "============================================================"
+  echo "  Welcome to <%=projectName%> dev container!"
+  echo "  To finish setup, run:"
+  echo "      revos init"
+  echo "============================================================"
+  echo ""
+fi
+unset __revos_need_setup

package/dist/templates/README.md

@@ -1,23 +1,91 @@
 # <%=projectName%>
 
-RevOS data engineering project for **<%=orgName%>** organization.
+RevOS data engineering project for **<%=orgName%>**.
+
+This project is designed to be opened in a Dev Container. All tooling — Python, Node, dbt, the Google Cloud CLI, the RevOS CLI, GitHub CLI, and Claude Code — comes pre-installed. The container is the supported development environment; you should rarely need to install anything on your host.
 
 ## Getting started
 
-1. Open this folder in VS Code and click **Reopen in Container** — the Dev Container installs all tools automatically.
-2. Inside the container, verify your setup:
+1. **Open in VS Code** and click **Reopen in Container** when prompted. First open builds the image (~1–2 min); subsequent opens are instant.
+
+2. **One-time setup inside the container.** Open a terminal and run:
+
+   ```bash
+   revos init    # signs you in via browser (if needed), then provisions the BigQuery service account key
+   ```
+
+   `revos init` detects it's running inside an existing project, skips the org prompt and scaffolding, and just fills in the missing GCP key. If you aren't authenticated yet, it opens the browser for sign-in first — the org is taken from `revos.yaml`.
+
+   **You won't need to repeat this.** Credentials persist in per-project Docker volumes, so every future `Rebuild Container`, restart, or VS Code reopen lands in a fully-authenticated state — the container will print `REVOS DEV CONTAINER — READY` on every start.
+
+3. **Verify everything is wired up.** Either look at the banner the container prints on every start (`REVOS DEV CONTAINER — READY` with your auth + GCP details), or run:
+
    ```bash
-   dbt --version
-   bq version
+   bq ls $REVOS_BQ_DATASET     # list tables in your BigQuery dataset
+   dbt debug                   # confirm dbt connection
+   revos status                # list local Connections/Cubes vs. the API
    ```
 
-## Project structure
+## Project layout
 
 ```
-dbt/models/
-  bronze/   # raw ingested data
-  silver/   # cleaned & conformed
-  gold/     # business-ready marts
-semantic/
-  cubes/    # Cube.dev cube definitions
+.
+├── revos.yaml                # binds this project to your RevOS org (do not edit)
+├── connections/              # sync pipelines (RevOS-managed; one YAML per Connection)
+├── cubes/                    # Cube.dev semantic model definitions (one YAML per Cube)
+├── dbt/
+│   ├── dbt_project.yml
+│   ├── profiles.yml          # pre-configured for BigQuery via $GOOGLE_APPLICATION_CREDENTIALS
+│   └── models/
+│       ├── bronze/           # raw ingested data — declared as dbt sources in schema.yml
+│       ├── silver/           # cleaned & conformed
+│       └── gold/             # business-ready marts
+├── .claude/                  # AI companion config + pre-installed skills
+├── .devcontainer/            # Dev Container definition
+├── AGENTS.md                 # context for AI coding agents
+└── CLAUDE.md                 # imports AGENTS.md
 ```
+
+## Common workflows
+
+| Task                                          | Command                              |
+| --------------------------------------------- | ------------------------------------ |
+| List data sources available on RevOS          | `revos sources list`                 |
+| Add a new data source (opens RevOS UI)        | `revos sources create`               |
+| Pull current Connections & Cubes from the API | `revos pull`                         |
+| Push local YAML changes back to the API       | `revos apply`                        |
+| Preview drift before applying                 | `revos diff`                         |
+| Run all dbt models                            | `dbt run`                            |
+| Run dbt tests                                 | `dbt test`                           |
+| Inspect a BigQuery table                      | `bq head -n 5 $REVOS_BQ_DATASET.<t>` |
+| Show all `revos` commands                     | `revos --help`                       |
+
+## Working with Claude Code
+
+This project ships pre-installed Claude skills under `.claude/skills/` for the common tasks:
+
+- **`explore-lakehouse`** — survey your BigQuery datasets and tables.
+- **`create-connections`** — author a Connection YAML from a Source's available streams.
+- **`create-cubes`** — build Cube.dev semantic models from gold-layer tables.
+- **`create-dbt-transformations`** — write bronze→silver→gold dbt models.
+- **`load-sample-data`** — seed BigQuery with example data when the warehouse is empty.
+- **`visualize-semantic-model`** — render the cube graph as an image.
+
+Inside the container, ask Claude things like _"create a Connection for our Stripe source"_ or _"build a silver model for the orders table"_ and it will use the matching skill.
+
+## Troubleshooting
+
+- **Container shows `SETUP REQUIRED` banner.** Run `revos init` in the container terminal — it handles login automatically.
+- **`bq` or `dbt` fails with auth errors.** Container's gcloud is not activated. Rebuild the container, or run `bash .devcontainer/post-start.sh` to re-activate.
+- **Start from a clean slate.** Wipe the per-project Docker volumes from your host:
+  ```bash
+  docker volume rm revos-<%=projectSlug%>-credentials \
+                  revos-<%=projectSlug%>-gcloud \
+                  revos-<%=projectSlug%>-claude
+  ```
+  Then `Rebuild Container` and rerun step 2.
+
+## Further reading
+
+- RevOS CLI reference: <https://cli.revos.dev>
+- This project's AI guidance: [`AGENTS.md`](./AGENTS.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revos/cli",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "description": "RevOS CLI for managing RevOS platform resources",
   "license": "MIT",
   "type": "module",

package/dist/templates/.devcontainer/setup.sh

@@ -1,35 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-# Copy mounted GCP service account key to vscode user's home
-if [ -f /tmp/.revos-gsa-creds.json ]; then
-  mkdir -p "$HOME/.revos"
-  cp /tmp/.revos-gsa-creds.json "$HOME/.revos/gsa-creds.json"
-  chmod 600 "$HOME/.revos/gsa-creds.json"
-fi
-
-# Copy mounted RevOS CLI credentials so revos commands work without re-login
-if [ -f /tmp/.revos-credentials.json ]; then
-  mkdir -p "$HOME/.revos"
-  cp /tmp/.revos-credentials.json "$HOME/.revos/credentials.json"
-  chmod 600 "$HOME/.revos/credentials.json"
-fi
-
-# Configure gcloud with service account and project
-GCP_KEY="$HOME/.revos/gsa-creds.json"
-if [ -f "$GCP_KEY" ]; then
-  gcloud auth activate-service-account --key-file="$GCP_KEY"
-fi
-if [ -n "${GOOGLE_CLOUD_PROJECT:-}" ]; then
-  gcloud config set project "$GOOGLE_CLOUD_PROJECT"
-fi
-
-# Fix Claude Code credentials permissions (volume is created as root)
-sudo chown -R vscode:vscode /home/vscode/.claude 2>/dev/null || true
-
-# Install RevOS CLI
-npm install -g @revos/cli
-
-# Symlink dbt profiles so `dbt run` works without --profiles-dir
-mkdir -p "$HOME/.dbt"
-ln -sf "$(pwd)/dbt/profiles.yml" "$HOME/.dbt/profiles.yml"