@revos/cli 0.2.0 → 0.2.2

package/dist/index.d.mts

@@ -1,4 +1,3 @@
-import { a as DiffEntry, c as OverlayFileData, d as PushResult, f as StatusResult, i as DiffChange, l as OverlayStatusInfo, n as CubeDefinition, o as DiffResult, p as SyncStatus, r as CubeOverlay, s as OverlayFile, t as Config, u as PullResult } from "./types-C_p_6rkj.mjs";
-import { A as ClerkEnv, B as tokenResponseToCredentials, C as LoadedOverlay, D as loadOverlaysByNames, E as loadOverlays, F as generatePKCEChallenge, G as isTokenExpired, H as startOAuthServer, I as getUserInfo, J as getConfig, K as loadCredentials, L as refreshAccessToken, M as PKCEChallenge, N as buildAuthorizationUrl, O as loadOverlaysFromDir, P as exchangeCodeForTokens, R as setClerkConfig, S as sanitizeFileName, T as loadOverlayFile, U as deleteCredentials, V as OAuthServerResult, W as getCredentialsPath, Y as ApiError, _ as createApiClient, a as DiffOptions, b as formatError, c as StatusOptions, d as PullOptions, f as PullService, g as ApiClient, h as PushService, i as DiffContext, j as ClerkOAuthConfig, k as saveOverlayToFile, l as StatusService, m as PushOptions, n as InitResult, o as DiffService, p as PushContext, q as saveCredentials, r as InitService, s as StatusContext, t as InitOptions, u as PullContext, v as unwrap, w as getLocalOverlayNames, x as isContentEqual, y as findRemoteOnlyOverlays, z as setClerkEnv } from "./index-KAzwt5vr.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-Y_ht_ja5.mjs";
-export { ApiClient, ApiError, AuthResult, AuthStatusInfo, ClerkEnv, ClerkOAuthConfig, ClerkUserInfo, Config, CubeDefinition, CubeOverlay, DiffChange, DiffContext, DiffEntry, DiffOptions, DiffResult, DiffService, InitOptions, InitResult, InitService, LoadedOverlay, OAuthCallbackResult, OAuthServerResult, OrgListResult, OrgSwitchResult, OrganizationInfo, OverlayFile, OverlayFileData, OverlayStatusInfo, PKCEChallenge, PullContext, PullOptions, PullResult, PullService, PushContext, PushOptions, PushResult, PushService, StatusContext, StatusOptions, StatusResult, StatusService, StoredCredentials, SyncStatus, TokenResponse, buildAuthorizationUrl, createApiClient, deleteCredentials, exchangeCodeForTokens, findRemoteOnlyOverlays, formatError, generatePKCEChallenge, getConfig, getCredentialsPath, getLocalOverlayNames, getUserInfo, isContentEqual, isTokenExpired, loadCredentials, loadOverlayFile, loadOverlays, loadOverlaysByNames, loadOverlaysFromDir, refreshAccessToken, sanitizeFileName, saveCredentials, saveOverlayToFile, setClerkConfig, setClerkEnv, startOAuthServer, tokenResponseToCredentials, unwrap };
+import { A as deleteCredentials, C as getUserInfo, D as tokenResponseToCredentials, E as setAuthEnv, F as DEFAULT_API_URL, I as getConfig, L as ApiError, M as isTokenExpired, N as loadCredentials, O as OAuthServerResult, P as saveCredentials, R as Config, S as getActiveAuthConfig, T as setAuthConfig, _ as AuthEnv, b as exchangeCodeForTokens, d as unwrap, f as resolveAppUrl, g as AuthConfig, h as AUTH_ENVS, i as index_d_exports, j as getCredentialsPath, k as startOAuthServer, l as ApiClient, m as sanitizeFileName, n as InitResult, p as formatError, r as InitService, t as InitOptions, u as createApiClient, v as PKCEChallenge, w as refreshAccessToken, x as generatePKCEChallenge, y as buildAuthorizationUrl } from "./index-BqKwXXAo.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-CGjxcj4L.mjs";
+export { AUTH_ENVS, ApiClient, ApiError, AuthConfig, AuthEnv, AuthResult, AuthStatusInfo, ClerkUserInfo, Config, DEFAULT_API_URL, InitOptions, InitResult, InitService, OAuthCallbackResult, OAuthServerResult, OrgListResult, OrgSwitchResult, OrganizationInfo, PKCEChallenge, StoredCredentials, TokenResponse, buildAuthorizationUrl, createApiClient, deleteCredentials, exchangeCodeForTokens, formatError, generatePKCEChallenge, getActiveAuthConfig, getConfig, getCredentialsPath, getUserInfo, index_d_exports as iac, isTokenExpired, loadCredentials, refreshAccessToken, resolveAppUrl, sanitizeFileName, saveCredentials, setAuthConfig, setAuthEnv, startOAuthServer, tokenResponseToCredentials, unwrap };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { A as getCredentialsPath, C as getUserInfo, D as tokenResponseToCredentials, E as setClerkEnv, M as loadCredentials, N as saveCredentials, O as startOAuthServer, P as ApiError, S as generatePKCEChallenge, T as setClerkConfig, _ as isContentEqual, a as PullService, b as buildAuthorizationUrl, c as loadOverlayFile, d as loadOverlaysFromDir, f as saveOverlayToFile, g as formatError, h as findRemoteOnlyOverlays, i as StatusService, j as isTokenExpired, k as deleteCredentials, l as loadOverlays, m as unwrap, o as PushService, p as createApiClient, r as DiffService, s as getLocalOverlayNames, t as InitService, u as loadOverlaysByNames, v as sanitizeFileName, w as refreshAccessToken, x as exchangeCodeForTokens, y as getConfig } from "./core-gKJ_V-K5.mjs";
-export { ApiError, DiffService, InitService, PullService, PushService, StatusService, buildAuthorizationUrl, createApiClient, deleteCredentials, exchangeCodeForTokens, findRemoteOnlyOverlays, formatError, generatePKCEChallenge, getConfig, getCredentialsPath, getLocalOverlayNames, getUserInfo, isContentEqual, isTokenExpired, loadCredentials, loadOverlayFile, loadOverlays, loadOverlaysByNames, loadOverlaysFromDir, refreshAccessToken, sanitizeFileName, saveCredentials, saveOverlayToFile, setClerkConfig, setClerkEnv, startOAuthServer, tokenResponseToCredentials, unwrap };
+import { A as deleteCredentials, C as getActiveAuthConfig, D as setAuthEnv, E as setAuthConfig, F as ApiError, M as isTokenExpired, N as loadCredentials, O as tokenResponseToCredentials, P as saveCredentials, S as generatePKCEChallenge, T as refreshAccessToken, _ as DEFAULT_API_URL, b as buildAuthorizationUrl, f as createApiClient, g as sanitizeFileName, h as formatError, j as getCredentialsPath, k as startOAuthServer, m as resolveAppUrl, p as unwrap, r as iac_exports, t as InitService, v as getConfig, w as getUserInfo, x as exchangeCodeForTokens, y as AUTH_ENVS } from "./core-CMrP5BQS.mjs";
+export { AUTH_ENVS, ApiError, DEFAULT_API_URL, InitService, buildAuthorizationUrl, createApiClient, deleteCredentials, exchangeCodeForTokens, formatError, generatePKCEChallenge, getActiveAuthConfig, getConfig, getCredentialsPath, getUserInfo, iac_exports as iac, isTokenExpired, loadCredentials, refreshAccessToken, resolveAppUrl, sanitizeFileName, saveCredentials, setAuthConfig, setAuthEnv, startOAuthServer, tokenResponseToCredentials, unwrap };

package/dist/{presets-Cvazkjmu.mjs → presets-CJbFbHlw.mjs}

@@ -1,21 +1,36 @@
-import { m as unwrap } from "./core-gKJ_V-K5.mjs";
-import { n as defineApiCommand, t as bodyFlag } from "./factory-D9sR_S_g.mjs";
+import { p as unwrap } from "./core-CMrP5BQS.mjs";
+import { n as createListRender, r as defineApiCommand, t as bodyFlag } from "./factory-C6XLqhT9.mjs";
 import { Args, Flags } from "@oclif/core";
 //#region src/adapters/oclif/presets.ts
+function camelToKebab(s) {
+	return s.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+}
 const listFlags = {
 	"page-size": Flags.integer({ description: "Maximum number of items to return" }),
 	"page-token": Flags.string({ description: "Token for the next page (from previous response)" }),
 	"order-by": Flags.string({ description: "Field to order results by (e.g. 'createdAt desc')" }),
 	filter: Flags.string({ description: "Filter expression" }),
-	fields: Flags.string({ description: "Comma-separated list of fields to include" })
+	fields: Flags.string({ description: "Comma-separated list of fields to include" }),
+	columns: Flags.string({
+		description: "Columns to display in table output (comma-separated). Overrides the resource default. Ignored with --json.",
+		helpValue: "a,b,c"
+	})
 };
 function getResource(api, key) {
 	return api[key];
 }
 function listCommand(spec) {
+	const pathParams = spec.pathParams ?? [];
+	const pathFlags = Object.fromEntries(pathParams.map((name) => [camelToKebab(name), Flags.string({
+		description: `${name} path parameter`,
+		required: true
+	})]));
 	return defineApiCommand({
 		description: spec.description,
-		flags: listFlags,
+		flags: {
+			...listFlags,
+			...pathFlags
+		},
 		call: async ({ api, flags }) => {
 			const resource = getResource(api, spec.resource);
 			if (!resource.list) throw new Error(`Resource '${String(spec.resource)}' has no list method`);
@@ -25,8 +40,10 @@ function listCommand(spec) {
 			if (flags["order-by"] !== void 0) params.orderBy = flags["order-by"];
 			if (flags.filter !== void 0) params.filter = flags.filter;
 			if (flags.fields !== void 0) params.fields = flags.fields;
+			for (const name of pathParams) params[name] = flags[camelToKebab(name)];
 			return unwrap(await resource.list(Object.keys(params).length > 0 ? params : void 0));
-		}
+		},
+		render: createListRender(spec.defaultColumns)
 	});
 }
 function getCommand(spec) {
@@ -44,14 +61,24 @@ function getCommand(spec) {
 	});
 }
 function createCommand(spec) {
+	const pathParams = spec.pathParams ?? [];
+	const pathFlags = Object.fromEntries(pathParams.map((name) => [camelToKebab(name), Flags.string({
+		description: `${name} path parameter`,
+		required: true
+	})]));
 	return defineApiCommand({
 		description: spec.description,
-		flags: { body: bodyFlag },
-		call: async ({ api, body }) => {
+		flags: {
+			body: bodyFlag,
+			...pathFlags
+		},
+		call: async ({ api, body, flags }) => {
 			const resource = getResource(api, spec.resource);
 			if (!resource.create) throw new Error(`Resource '${String(spec.resource)}' has no create method`);
 			if (body === void 0) throw new Error("--body is required (inline JSON, '@path' for file, or '-' for stdin)");
-			return unwrap(await resource.create({ body }));
+			const params = { body };
+			for (const name of pathParams) params[name] = flags[camelToKebab(name)];
+			return unwrap(await resource.create(params));
 		}
 	});
 }

package/dist/templates/.claude/settings.json

@@ -0,0 +1,39 @@
+{
+  "permissions": {
+    "deny": [
+      "Read(~/.revos/**)",
+      "Read(~/.config/gcloud/**)",
+      "Read(/tmp/.revos-gsa-creds.json)",
+      "Read(/tmp/.revos-credentials.json)",
+      "Read(~/.claude/**)",
+      "Read(//proc/*/environ)",
+      "Edit(~/.revos/**)",
+      "Write(~/.revos/**)",
+      "Edit(~/.config/gcloud/**)",
+      "Write(~/.config/gcloud/**)",
+      "Edit(.claude/settings*.json)",
+      "Write(.claude/settings*.json)",
+      "Edit(.claude/hooks/**)",
+      "Write(.claude/hooks/**)",
+      "Edit(.claude/commands/**)",
+      "Write(.claude/commands/**)",
+      "Edit(.mcp.json)",
+      "Write(.mcp.json)",
+      "Bash(curl:*)",
+      "Bash(wget:*)",
+      "Bash(nc:*)",
+      "Bash(ncat:*)",
+      "Bash(socat:*)",
+      "Bash(env)",
+      "Bash(env:*)",
+      "Bash(printenv)",
+      "Bash(printenv:*)",
+      "Bash(gcloud auth print-access-token:*)",
+      "Bash(gcloud auth print-identity-token:*)",
+      "Bash(gcloud auth application-default print-access-token:*)"
+    ]
+  },
+  "sandbox": {
+    "enabled": true
+  }
+}

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

@@ -22,12 +22,12 @@
   "postCreateCommand": "bash .devcontainer/setup.sh",
   "mounts": [
     {
-      "source": "${localEnv:HOME}/.revos/<%=projectSlug%>-gsa-creds.json",
+      "source": "${localEnv:HOME}${localEnv:USERPROFILE}/.revos/<%=projectSlug%>-gsa-creds.json",
       "target": "/tmp/.revos-gsa-creds.json",
       "type": "bind"
     },
     {
-      "source": "${localEnv:HOME}/.revos/credentials.json",
+      "source": "${localEnv:HOME}${localEnv:USERPROFILE}/.revos/credentials.json",
       "target": "/tmp/.revos-credentials.json",
       "type": "bind"
     },

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

@@ -24,6 +24,9 @@ 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
 

package/dist/templates/AGENTS.md

@@ -4,19 +4,42 @@ This is a RevOS data engineering project for **<%=orgName%>** organization.
 
 ## Project Structure
 
-- `dbt/models/bronze/` — raw ingested data
-- `dbt/models/silver/` — cleaned & conformed
-- `dbt/models/gold/` — business-ready marts
-- `semantic/` — Cube.dev cube definitions
+- `dbt/models/bronze/` — `schema.yml` only (declares raw tables as dbt sources; no SQL files)
+- `dbt/models/silver/` — cleaned & conformed; reads raw via `{{ source('bronze', '<table>') }}`
+- `dbt/models/gold/` — business-ready marts; reads silver via `{{ ref() }}`
+- `cubes/` — first-class Cube.dev semantic model definitions
 
 ## Key Commands
 
-| Command               | Description                      |
-| --------------------- | -------------------------------- |
-| `revos auth login`    | Authenticate with RevOS          |
-| `revos overlays push` | Push Cube overlays to RevOS      |
-| `revos overlays pull` | Pull Cube overlays from RevOS    |
-| `revos overlays diff` | Compare local vs remote overlays |
-| `dbt run`             | Run dbt models                   |
-| `dbt test`            | Test dbt models                  |
-| `bq ls`               | List BigQuery datasets/tables    |
+| Command                     | Description                                |
+| --------------------------- | ------------------------------------------ |
+| `revos auth login`          | Authenticate with RevOS                    |
+| `revos apply`               | Reconcile local Connections/Cubes with API |
+| `revos pull`                | Pull current Connections/Cubes from API    |
+| `revos diff`                | Compare local YAML against the API         |
+| `revos status`              | Show sync status of local resources        |
+| `revos sources list`        | List data sources                          |
+| `revos sources get <id>`    | Get a data source by ID                    |
+| `revos sources create`      | Open RevOS UI to add a data source         |
+| `revos sources update <id>` | Open RevOS UI to edit a data source        |
+| `revos sources delete <id>` | Delete a data source                       |
+| `dbt run`                   | Run dbt models                             |
+| `dbt test`                  | Test dbt models                            |
+| `bq ls`                     | List BigQuery datasets/tables              |
+
+## Data Sources
+
+When the user wants to add or manage data sources:
+
+- To add a new data source: suggest `revos sources create` (opens RevOS UI)
+- To view existing sources: suggest `revos sources list`
+- If a BigQuery dataset is empty or has no tables, mention that a data source can be configured with `revos sources create`, or sample data can be loaded if available
+
+## Security & sandboxing
+
+`.claude/settings.json` in this project configures two layers of protection:
+
+- **Permission deny rules** block reading credential paths (`~/.revos/`, `~/.config/gcloud/`, `~/.claude/`) and editing `.claude/settings.json`, hooks, and MCP config. These tool-layer rules always apply to Claude's built-in Read/Edit/Write tools.
+- **OS-level sandbox** (`sandbox.enabled: true`) extends the same restrictions to Bash subprocesses via Seatbelt (macOS) or bubblewrap (Linux).
+
+**Inside this Dev Container the sandbox cannot start** — Docker's default seccomp profile blocks the namespace-creation syscalls bubblewrap needs. Claude Code prints a one-time warning at launch and runs without OS-level isolation. In that fallback state, deny rules still cover Claude's Read/Edit/Write tools, but Bash commands like `cat ~/.revos/credentials.json` are not blocked. The sandbox does activate when Claude Code runs on a macOS host directly, outside the container.

package/dist/templates/dbt/dbt_project.yml

@@ -17,6 +17,6 @@ models:
     bronze:
       +materialized: table
     silver:
-      +materialized: table
+      +materialized: view
     gold:
-      +materialized: table
+      +materialized: view

package/dist/templates/skills/create-connections/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: create-connections
+description: >
+  Create a RevOS Connection YAML that syncs data from a Source into the
+  org's data warehouse. Use whenever the user asks to: add a connection,
+  set up a sync, ingest a table, pipe data from a source, configure streams,
+  pick which tables to ingest, or wire up a Source. The skill picks a sensible stream subset
+  (especially important for databases — most projects don't want every table)
+  and confirms the choice before writing YAML.
+---
+
+# Create Connection
+
+## Purpose
+
+Author a `Connection` YAML under `connections/<name>.yaml` that ingests selected streams from a Source into the org's data warehouse. Each connection is a complete, standalone document — `revos apply` reads it and reconciles with the API.
+
+The hard part is **stream selection** and **sync-mode choice**, not the YAML shape. Most sources expose far more streams than a project actually needs; databases especially. Pick deliberately, confirm with the user, then write.
+
+---
+
+## Prerequisites
+
+- The Source already exists on the server (you'll get its `id` via `revos sources list`). If the user wants to ingest from a source that isn't created yet, stop and tell them to run `revos sources create` first — source configuration (connector picker, credentials, OAuth) lives in the RevOS UI.
+- `revos auth status` shows authenticated. If not, ask the user to run `revos auth login`.
+
+---
+
+## User Checkpoints
+
+The skill makes two decisions that benefit from explicit confirmation. Don't skip them — wrong streams or wrong sync mode wastes warehouse storage and reload time.
+
+### Checkpoint 1: Stream selection
+
+After discovering streams and asking the user about their use case, propose a subset with one-line rationale per stream. Wait for confirmation or edits before moving on.
+
+### Checkpoint 2: Sync-mode and key choices
+
+After deriving sync mode + cursor + primary key for each selected stream, present the table and confirm before writing the file. Most users skim and approve; some will want to flip a stream to `full_refresh_overwrite` or change the cursor.
+
+---
+
+# Workflow
+
+## Phase 1: Identify the Source
+
+Run `revos sources list --json` and match on the server-side `name` (or run `revos sources list` for a scannable table). Record the source's `id` — that goes into the Connection YAML as `spec.source.id`.
+
+If no source was named, ask the user which one. Don't proceed without an id.
+
+## Phase 2: Discover streams
+
+```bash
+revos sources list-streams <id> --json
+```
+
+This returns an array of objects shaped like:
+
+```json
+{
+  "streamName": "customers",
+  "streamnamespace": "public",
+  "syncModes": ["full_refresh_overwrite", "incremental_deduped_history", ...],
+  "defaultCursorField": ["updated_at"],
+  "sourceDefinedCursorField": false,
+  "sourceDefinedPrimaryKey": [["id"]],
+  "propertyFields": [["id"], ["email"], ["updated_at"], ...]
+}
+```
+
+Save the full response — you'll reference it in later phases. The `syncModes` array narrows what's valid for this stream against the project's destination; never propose a mode that isn't in this list.
+
+Two things worth knowing about the shape:
+
+- **Database sources usually leave `defaultCursorField` empty** even when they advertise incremental modes. They expose every column via `propertyFields` and let you pick. Plan to fall back to `propertyFields` for DB sources; SaaS sources typically pre-fill `defaultCursorField` with the right field.
+- **`streamnamespace` is set for databases** (e.g. `public`, `dbo`) and absent for most SaaS sources. The YAML needs the `namespace:` line whenever the discovery response includes one — drop the line for streams that don't have it.
+
+## Phase 3: Ask about the use case
+
+Before proposing streams, ask **one short question** to anchor the selection. Examples:
+
+- "What do you want to analyze with this connection? E.g. revenue per customer, support ticket trends, marketing funnel."
+- "Which part of the source matters here — sales pipeline, finance records, product usage?"
+
+Keep it open-ended; one sentence from the user is enough. The goal is to filter out obviously-irrelevant streams (audit logs, internal queues, system tables) and prioritize business entities. Skip this question only if the user already stated the goal in their initial request.
+
+## Phase 4: Propose a stream subset (Checkpoint 1)
+
+Apply these rules in order:
+
+1. **Drop technical/system streams** unless the user's goal explicitly needs them. Names matching any of: starts with `pg_`, `information_schema`, `_airbyte`, `temp_`, `tmp_`, `audit_`, `system_`, `migration`, `schema_migrations`; ends with `_history`, `_log`, `_audit`, `_archive`. Be conservative — when in doubt, include it and flag it.
+
+2. **For databases** (postgres / mysql / mssql / mongodb-style sources, recognizable by many streams and namespaces like `public`, `dbo`, `sales`): expect to drop 30–80% of streams. Project use cases rarely need every operational table. Prefer streams whose names match the user's goal (`orders`, `customers`, `products` for revenue analysis; `tickets`, `contacts`, `messages` for support).
+
+3. **For SaaS sources** (small flat stream list, no namespace, names like `companies`, `deals`, `tickets`, `engagements`): include all core business entities by default. Drop only obvious noise (`*_metadata`, `*_history`, `*_changelog`).
+
+4. **Be honest about uncertainty.** If you can't tell what a stream is from its name, say so — don't fabricate a rationale.
+
+Present the proposal as a table the user can scan:
+
+```
+Proposed streams (12 of 47):
+
+  customers         core entity — revenue analysis needs this
+  orders            transactions table; cursor: updated_at
+  order_items       order line items; needed to break revenue by SKU
+  products          dimension table for orders/order_items
+  ...
+
+Dropped (35): pg_stat_*, _airbyte_internal_*, audit_*, schema_migrations,
+              user_sessions (not in scope for revenue analysis), ...
+```
+
+Ask: "Look right? Anything to add or remove?" Wait for the user. They might say "add `users`" or "drop `products`, we don't need it" — adjust.
+
+## Phase 5: Determine sync mode, cursor, and primary key per stream
+
+For each selected stream, the choice is driven by what the source supports (`syncModes`) and what fields it advertises. The four sync modes you'll use:
+
+| Sync mode                        | Requires                   | When to use                                                                                                                       |
+| -------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `incremental_deduped_history`    | cursor **and** primary key | Best default. Source advertises a cursor (e.g. `updated_at`) and a PK. Only new/changed rows pull; duplicates collapse on PK.     |
+| `incremental_append`             | cursor only                | Source has a cursor but no PK (event streams, append-only logs). Rows accumulate; no deduplication.                               |
+| `full_refresh_overwrite_deduped` | primary key only           | Source has a PK but no usable cursor. Each sync replaces the destination table, deduplicated by PK. Fine for small/medium tables. |
+| `full_refresh_overwrite`         | nothing                    | Small dimension tables (<10k rows), or when nothing else works. Each sync overwrites.                                             |
+
+Decision algorithm per stream:
+
+1. Pick the **strongest mode the source supports**, in this priority order: `incremental_deduped_history` → `incremental_append` → `full_refresh_overwrite_deduped` → `full_refresh_overwrite`. Skip any mode not in the stream's `syncModes` array.
+2. For modes requiring a cursor: use `defaultCursorField` if non-empty. Otherwise look at `propertyFields` for the first available timestamp-looking field (`updated_at`, `modified_at`, `last_modified`, `_updated`, `timestamp`). If nothing fits, drop down to a full-refresh mode.
+3. For modes requiring a primary key: use `sourceDefinedPrimaryKey` if non-empty. Otherwise look in `propertyFields` for an `id`-like field (`id`, `<entity>_id`, `uuid`, `key`). If nothing fits, drop down to `incremental_append` or `full_refresh_overwrite`.
+
+Use compact notation when presenting (Checkpoint 2):
+
+```
+Stream             Sync mode                       Cursor        Primary key
+customers          incremental_deduped_history     updated_at    id
+orders             incremental_deduped_history     updated_at    id
+order_items        incremental_append              created_at    —
+products           full_refresh_overwrite          —             —
+```
+
+Ask: "Sync modes look right? Any changes?" Common edits: dropping a large table to `full_refresh_overwrite` only if it's small/static; switching cursor field.
+
+## Phase 6: Write the YAML
+
+Two names to pick, with different rules:
+
+- **`metadata.name`** — the local IaC slug. Filename-friendly: lowercase, alphanumerics + hyphens. Anchors the YAML file (`connections/<metadata.name>.yaml`) and how other resources refer to this connection. Derive from the source and scope: `hubspot-sales`, `postgres-prod-revenue`, `stripe-billing`.
+- **`spec.name`** — the human-readable label shown in the RevOS UI. Short, sentence case, spaces fine, no underscores. Describe what the connection syncs so a teammate scanning the UI knows without opening it. Patterns that work: `"HubSpot sales pipeline"`, `"Postgres prod → revenue tables"`, `"Stripe billing & subscriptions"`. Avoid reusing the slug here — `hubspot-sales` is a worse `spec.name` than `HubSpot sales pipeline`.
+
+If a file already exists at the target path, ask whether to overwrite or pick a different name.
+
+Template:
+
+```yaml
+apiVersion: revos/v1
+kind: Connection
+metadata:
+  name: hubspot-sales
+spec:
+  name: HubSpot sales pipeline
+  source: { id: <id from `revos sources list`> }
+  schedule: { units: 24, timeUnit: hours }
+  status: active
+  streams:
+    - name: customers
+      namespace: public # omit if the stream has no namespace
+      syncMode: incremental_deduped_history
+      cursorField: [updated_at]
+      primaryKey: [[id]]
+```
+
+Notes:
+
+- `source.id` is the server id of the Source (e.g. `src_abc123`). Sources are not IaC — get the id with `revos sources list`.
+- `primaryKey` is a list of lists — each inner list is one PK column path, supporting nested keys. Most cases it's `[[id]]`.
+- `cursorField` is a flat list of path segments. Top-level field is `[updated_at]`; nested would be `[meta, modified_at]`.
+- Omit `cursorField` and `primaryKey` for `full_refresh_overwrite`. Omit only `cursorField` for `full_refresh_overwrite_deduped`. CLI validation rejects missing required fields at apply time, so keep this clean.
+- Don't set `metadata.id` or `spec.prefix` — both are filled in by `revos apply` on first create.
+
+**Stream mappers** (`streams[].mappers`) are server-side transformations applied before rows land in BigQuery — hashing PII, renaming columns, dropping fields, filtering rows, encrypting values. Default to a clean sync without them. Load [references/mappers.md](references/mappers.md) when either:
+
+- The user mentions masking, hashing, PII, renaming, dropping a column, filtering rows, or encryption.
+- A selected stream's `propertyFields` includes obviously sensitive columns (`email`, `phone`, `ssn`, `ip_address`, full-name pairs, payment fields). In that case load the reference, then proactively suggest a mapper with the field name and rationale, and ask the user to confirm before adding it. Don't quietly insert mappers — masking the wrong field corrupts analysis.
+
+## Phase 7: Validate locally
+
+```bash
+revos diff
+```
+
+The CLI parses the YAML through zod and reports what would change. Look for:
+
+- **Parse errors** — schema rejections (missing required fields, invalid sync mode). Fix and re-run.
+- **Drift report** — the new connection should appear as a single `create` entry.
+
+If `revos diff` is clean, hand back: "Connection YAML written to `connections/<slug>.yaml` and validated. Run `revos apply` to create it on the server."
+
+If validation fails, share the error verbatim and fix before declaring success.
+
+---
+
+# Common pitfalls
+
+- **Picking a sync mode the source doesn't support.** Always intersect your choice with the stream's `syncModes` array from Phase 2. The API validates this server-side; better to catch it locally.
+- **Using a source name where the server id is expected.** `spec.source.id` is the server id (e.g. `src_abc123`), not a display name or a slug. Always pull it from `revos sources list`.
+- **Setting `cursorField` on a `full_refresh_*` mode.** CLI validation tolerates extra fields but it's noise. Omit fields that don't apply to the chosen mode.
+- **Proposing every stream.** Especially for databases. If the user says "all of them" after seeing the proposal, fine — but offer the curated list first.
+- **Inventing fields.** Only use `cursorField` and `primaryKey` values that appear in the discovery response (`defaultCursorField`, `sourceDefinedPrimaryKey`, or `propertyFields`).

package/dist/templates/skills/create-connections/references/mappers.md

@@ -0,0 +1,152 @@
+# Stream mappers
+
+Stream mappers are **server-side transformations** applied per stream before rows land in BigQuery. They run inside the sync pipeline, so even a direct BigQuery query sees only the transformed values — no way for downstream analysts to bypass them.
+
+Five mapper types are supported. They're all opt-in: a clean sync needs none of them. Add them only when the user asks for masking, renaming, dropping, filtering, or encryption.
+
+| Type              | Use when                                                                                                            |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `hashing`         | One-way obfuscation of PII (email, name, IP). Analysts get a joinable but irreversible identifier.                  |
+| `field-renaming`  | Rename a column at ingest. Useful when the source field name leaks sensitivity (`ssn` → `ssn_redacted`).            |
+| `field-filtering` | Drop a column entirely. Use when the value should never reach the warehouse (notes, internal flags, free-text PII). |
+| `row-filtering`   | Drop entire rows that match a predicate. Use to exclude test/demo data, soft-deleted rows, internal accounts.       |
+| `encryption`      | Reversible obfuscation. Use when a process downstream of BigQuery needs to recover the plaintext.                   |
+
+Mappers live under `streams[].mappers` as an ordered list. The configuration body always sits under `mapperConfiguration` — that's the schema shape, not a stylistic choice.
+
+---
+
+## When to proactively suggest a mapper
+
+The skill should propose a mapper without being asked when the stream's `propertyFields` includes anything obviously sensitive:
+
+- **Hash, don't store plaintext**: `email`, `email_address`, `phone`, `phone_number`, `ip_address`, `ssn`, `tax_id`, `national_id`, `passport`, `dob`, `date_of_birth`, `full_name`, `first_name + last_name` pairs.
+- **Drop entirely**: free-text fields whose names hint at user-entered content (`notes`, `comments`, `internal_notes`, `description`) — unless the user said they need them for analysis.
+- **Encrypt (reversible)**: payment-method fields (`card_number`, `iban`, `account_number`) when the user has indicated a downstream process needs the original values.
+
+When suggesting, name the field and the mapper type, explain why, and ask the user to confirm or skip. Never quietly insert a mapper the user didn't approve — masking the wrong field corrupts analysis. Be especially conservative for `encryption`: a missing `key` value makes the YAML pass schema validation but the sync fails at runtime.
+
+---
+
+## Hashing
+
+One-way hash that preserves joinability (the same input always produces the same hash). Default to `SHA-256` — it's the safest choice unless the user has a reason to prefer something else.
+
+```yaml
+streams:
+  - name: customers
+    namespace: public
+    syncMode: incremental_deduped_history
+    cursorField: [updated_at]
+    primaryKey: [[id]]
+    mappers:
+      - type: hashing
+        mapperConfiguration:
+          targetField: email
+          method: SHA-256
+          fieldNameSuffix: _hashed
+```
+
+- `targetField`: the source column to hash. Must match a field in `propertyFields`.
+- `method`: one of `MD2`, `MD5`, `SHA-1`, `SHA-224`, `SHA-256`, `SHA-384`, `SHA-512`. MD5/SHA-1 are weak — only use them if the user explicitly asks (e.g. matching an existing hashed dataset).
+- `fieldNameSuffix`: appended to the column name in the destination. So `email` becomes `email_hashed` in BigQuery. Omit if the user wants to replace the column in place — but suffix is the safer default since it makes the transformation visible.
+
+---
+
+## Field renaming
+
+Rename a column on its way into the warehouse. Use when the source name itself is sensitive (column called `ssn` becomes `ssn_redacted` after a separate hashing/filtering step) or when the source uses awkward names you want analysts to see clean.
+
+```yaml
+mappers:
+  - type: field-renaming
+    mapperConfiguration:
+      originalFieldName: ssn
+      newFieldName: ssn_redacted
+```
+
+Rename runs after hashing — chain them when you want both: hash to `ssn_hashed`, then rename if needed.
+
+---
+
+## Field filtering
+
+Drop a column entirely from the destination table. The value never lands in BigQuery.
+
+```yaml
+mappers:
+  - type: field-filtering
+    mapperConfiguration:
+      targetField: internal_notes
+```
+
+Prefer this over hashing when the value has no analytical use — there's no reason to store a hashed `internal_notes` column when you can just drop it.
+
+---
+
+## Row filtering
+
+Drop rows that match a predicate. Use to exclude test data, soft-deleted records, internal accounts, etc.
+
+The `conditions` tree uses nested boolean operators (`AND`, `OR`, `NOT`) and leaf comparisons (`EQUAL`, `NOT_EQUAL`, others). **The predicate keeps rows where it evaluates to true** — so to drop rows, wrap the match condition in `NOT`.
+
+```yaml
+mappers:
+  # Keep rows where is_test != "true". Test rows get dropped.
+  - type: row-filtering
+    mapperConfiguration:
+      conditions:
+        type: NOT
+        conditions:
+          - type: EQUAL
+            fieldName: is_test
+            comparisonValue: "true"
+```
+
+Gotchas:
+
+- **Compare against real sentinel values**, not empty strings or nulls — empty-string comparisons behave unreliably across source connectors.
+- **Boolean fields**: most sources serialize booleans as strings on the wire, so the `comparisonValue` is `"true"` / `"false"`, not `true` / `false`. Confirm against `propertyFields` if unsure.
+- **The keep-vs-drop direction is easy to flip.** Re-read the predicate after writing it: "this filter keeps rows where **_, so it drops rows where _**."
+
+---
+
+## Encryption
+
+Reversible obfuscation. Use only when a process downstream of BigQuery genuinely needs to recover the plaintext — otherwise prefer hashing or filtering.
+
+```yaml
+mappers:
+  - type: encryption
+    mapperConfiguration:
+      algorithm: AES
+      targetField: card_number
+      fieldNameSuffix: _enc
+      key: ${env.AES_KEY}
+      mode: GCM
+      padding: NoPadding
+```
+
+- `algorithm`: `RSA` or `AES`.
+- `mode` (AES only): `CBC`, `CFB`, `OFB`, `CTR`, `GCM`, `ECB`. Default to `GCM` — it's authenticated and resistant to tampering. Only fall back to others if the user has a stated reason.
+- `padding` (AES only): `NoPadding` or `PKCS5Padding`. With `GCM`/`CTR`/`CFB`/`OFB`, use `NoPadding`. With `CBC`/`ECB`, use `PKCS5Padding`.
+- `key`: the encryption key. Reference an environment variable with `${env.VAR_NAME}` — never hardcode the key in YAML. Tell the user they need to set the env var in the project's deployment config.
+
+---
+
+## Ordering
+
+Mappers in `streams[].mappers` run in array order. When chaining (e.g. hash then rename), put them in the order you want them applied. Reordering changes the result — hashing after renaming targets the new field name, which is rarely what you want.
+
+A safe pattern when both hashing and renaming a sensitive column:
+
+```yaml
+mappers:
+  - type: hashing
+    mapperConfiguration:
+      { targetField: email, method: SHA-256, fieldNameSuffix: _hashed }
+  - type: field-filtering
+    mapperConfiguration: { targetField: email } # drop the plaintext column
+```
+
+This produces only `email_hashed` in BigQuery — the original `email` never lands.