@owlmetry/cli 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,44 @@
+# @owlmetry/cli
+
+CLI for [OwlMetry](https://owlmetry.com) — self-hosted metrics tracking for mobile and backend apps.
+
+Manage projects, apps, metrics, funnels, and events from the terminal. Ships with AI skill files to teach your coding agent how to use OwlMetry.
+
+## Install
+
+```bash
+npm install -g @owlmetry/cli
+```
+
+## Quick Start
+
+```bash
+# Sign up or log in
+owlmetry auth send-code --email you@example.com
+owlmetry auth verify --email you@example.com --code 123456
+
+# Save your credentials
+owlmetry setup --endpoint https://api.owlmetry.com --api-key owl_agent_...
+
+# Explore
+owlmetry projects
+owlmetry apps
+owlmetry events --last 1h
+owlmetry metrics
+owlmetry funnels
+```
+
+## AI Skills
+
+This package bundles skill files that teach AI agents (Claude Code, Codex, etc.) how to use OwlMetry — including the CLI, Node SDK, and Swift SDK.
+
+```bash
+owlmetry skills
+```
+
+This prints the absolute paths to each skill file. Point your agent to these files to give it full OwlMetry knowledge.
+
+## Links
+
+- [Website](https://owlmetry.com)
+- [GitHub](https://github.com/Jasonvdb/owlmetry)

package/dist/index.cjs

@@ -5757,6 +5757,10 @@ var OwlMetryClient = class {
     }
     return await response.json();
   }
+  // Auth
+  async whoami() {
+    return this.request("GET", "/v1/auth/whoami");
+  }
   // Projects
   async listProjects() {
     const result = await this.request("GET", "/v1/projects");
@@ -5916,6 +5920,7 @@ var import_node_fs = require("fs");
 var import_node_path = require("path");
 var import_node_os2 = require("os");
 var DEFAULT_ENDPOINT = "https://api.owlmetry.com";
+var DEFAULT_INGEST_ENDPOINT = "https://ingest.owlmetry.com";
 var CONFIG_DIR = (0, import_node_path.join)((0, import_node_os2.homedir)(), ".owlmetry");
 var CONFIG_FILE = (0, import_node_path.join)(CONFIG_DIR, "config.json");
 function loadConfig() {
@@ -5930,12 +5935,59 @@ function saveConfig(config) {
   (0, import_node_fs.mkdirSync)(CONFIG_DIR, { recursive: true });
   (0, import_node_fs.writeFileSync)(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n", "utf-8");
 }
+function getActiveProfile(config, teamHint) {
+  const entries = Object.entries(config.teams);
+  if (entries.length === 0) {
+    throw new Error("No team profiles configured. Run `owlmetry auth verify` to add one.");
+  }
+  if (!teamHint) {
+    const profile = config.teams[config.active_team];
+    if (!profile) {
+      throw new Error(
+        `Active team "${config.active_team}" not found in config. Run \`owlmetry auth verify\` to re-authenticate.`
+      );
+    }
+    return { teamId: config.active_team, profile };
+  }
+  if (config.teams[teamHint]) {
+    return { teamId: teamHint, profile: config.teams[teamHint] };
+  }
+  for (const [id, profile] of entries) {
+    if (profile.team_slug === teamHint) {
+      return { teamId: id, profile };
+    }
+  }
+  const lower = teamHint.toLowerCase();
+  for (const [id, profile] of entries) {
+    if (profile.team_name.toLowerCase() === lower) {
+      return { teamId: id, profile };
+    }
+  }
+  const available = entries.map(([id, p]) => `  ${id}  ${p.team_name} (${p.team_slug})`).join("\n");
+  throw new Error(`No team matching "${teamHint}". Available teams:
+${available}`);
+}
+function listProfiles(config) {
+  return Object.entries(config.teams).map(([teamId, profile]) => ({
+    teamId,
+    profile,
+    active: teamId === config.active_team
+  }));
+}
 function resolveConfig(opts) {
   const envEndpoint = opts.endpoint ?? process.env.OWLMETRY_ENDPOINT;
   const envApiKey = opts.apiKey ?? process.env.OWLMETRY_API_KEY;
   const file = envEndpoint && envApiKey ? null : loadConfig();
-  const endpoint = envEndpoint ?? file?.endpoint;
-  const api_key = envApiKey ?? file?.api_key;
+  let endpoint = envEndpoint;
+  let api_key = envApiKey;
+  let ingest_endpoint = file?.ingest_endpoint;
+  if (file && !api_key) {
+    const { profile } = getActiveProfile(file, opts.team);
+    api_key = profile.api_key;
+  }
+  if (!endpoint) {
+    endpoint = file?.endpoint;
+  }
   if (!endpoint) {
     throw new Error(
       "Missing endpoint. Use --endpoint, OWLMETRY_ENDPOINT env var, or run `owlmetry auth login`."
@@ -5946,7 +5998,7 @@ function resolveConfig(opts) {
       "Missing API key. Use --api-key, OWLMETRY_API_KEY env var, or run `owlmetry auth login`."
     );
   }
-  return { endpoint, api_key };
+  return { endpoint, api_key, ingest_endpoint };
 }
 function getGlobals(cmd) {
   return cmd.optsWithGlobals();
@@ -5979,16 +6031,42 @@ var setupCommand = new Command("setup").description("Configure CLI endpoint and
     endpoint: globals.endpoint,
     apiKey: globals.apiKey
   });
+  let teamId = "_manual";
+  let teamName = "Manual Setup";
+  let teamSlug = "manual";
   try {
-    await client.listProjects();
+    const whoami = await client.whoami();
+    if (whoami.team) {
+      teamId = whoami.team.id;
+      teamName = whoami.team.name;
+      teamSlug = whoami.team.slug;
+    }
   } catch (err) {
     console.error(
       source_default.red(`Failed to connect: ${err instanceof Error ? err.message : String(err)}`)
     );
     process.exit(1);
   }
-  saveConfig({ endpoint: globals.endpoint, api_key: globals.apiKey });
-  console.log(source_default.green("Configuration saved to ~/.owlmetry/config.json"));
+  const ingestEndpoint = globals.ingestEndpoint || globals.endpoint;
+  const existing = loadConfig();
+  const config = {
+    endpoint: globals.endpoint,
+    ingest_endpoint: ingestEndpoint,
+    active_team: teamId,
+    teams: {
+      ...existing?.teams,
+      [teamId]: {
+        api_key: globals.apiKey,
+        team_name: teamName,
+        team_slug: teamSlug
+      }
+    }
+  };
+  saveConfig(config);
+  console.log(source_default.green("\u2713 Configuration saved to ~/.owlmetry/config.json"));
+  console.log(`  Team:             ${teamName}`);
+  console.log(`  API endpoint:     ${globals.endpoint}`);
+  console.log(`  Ingest endpoint:  ${ingestEndpoint}`);
 });
 
 // src/commands/projects.ts
@@ -6494,6 +6572,12 @@ init_cjs_shims();
 function resolveEndpoint(globals) {
   return globals.endpoint || process.env.OWLMETRY_ENDPOINT || DEFAULT_ENDPOINT;
 }
+function resolveIngestEndpointForAuth(globals, endpoint) {
+  const explicit = globals.ingestEndpoint ?? process.env.OWLMETRY_INGEST_ENDPOINT;
+  if (explicit) return explicit;
+  if (endpoint === DEFAULT_ENDPOINT) return DEFAULT_INGEST_ENDPOINT;
+  return endpoint;
+}
 async function apiPost(endpoint, path, body) {
   const res = await fetch(`${endpoint.replace(/\/+$/, "")}${path}`, {
     method: "POST",
@@ -6552,19 +6636,38 @@ authCommand.command("verify").description("Verify code and get an agent API key"
     }
     process.exit(1);
   }
-  const { api_key, team, project, app, is_new_setup } = data;
-  if (!api_key) {
-    console.error(source_default.red("No API key returned"));
+  const { api_key, team } = data;
+  if (!api_key || !team) {
+    console.error(source_default.red("No API key or team info returned"));
     process.exit(1);
   }
-  saveConfig({ endpoint, api_key });
+  const ingestEndpoint = resolveIngestEndpointForAuth(globals, endpoint);
+  const existing = loadConfig();
+  const config = {
+    endpoint,
+    ingest_endpoint: ingestEndpoint,
+    active_team: team.id,
+    teams: {
+      ...existing?.teams,
+      [team.id]: {
+        api_key,
+        team_name: team.name,
+        team_slug: team.slug
+      }
+    }
+  };
+  saveConfig(config);
+  const profileCount = Object.keys(config.teams).length;
   if (format === "json") {
-    console.log(JSON.stringify({ api_key, endpoint, team, project, app, is_new_setup }, null, 2));
+    console.log(JSON.stringify({ api_key, endpoint, ingest_endpoint: ingestEndpoint, team }, null, 2));
   } else {
     console.log(source_default.green("\u2713 Authenticated! Config saved to ~/.owlmetry/config.json"));
-    console.log(`  Team:    ${team?.name}`);
-    if (project) console.log(`  Project: ${project.name}`);
-    if (app) console.log(`  App:     ${app.name} (${app.platform})`);
+    console.log(`  Team:             ${team.name}`);
+    console.log(`  API endpoint:     ${endpoint}`);
+    console.log(`  Ingest endpoint:  ${ingestEndpoint}`);
+    if (profileCount > 1) {
+      console.log(`  Profiles:         ${profileCount} teams configured`);
+    }
   }
 });
 
@@ -6976,10 +7079,104 @@ ${source_default.dim("Point your AI agent to these files to teach it how to use
   );
 });
 
+// src/commands/whoami.ts
+init_cjs_shims();
+var whoamiCommand = new Command("whoami").description("Show current authentication status and identity").action(async (_opts, cmd) => {
+  const { client, globals } = createClient(cmd);
+  const data = await client.whoami();
+  if (globals.format === "json") {
+    const config2 = loadConfig();
+    const profiles = config2 ? listProfiles(config2) : [];
+    console.log(JSON.stringify({
+      ...data,
+      configured_profiles: profiles.map((p) => ({
+        team_id: p.teamId,
+        team_name: p.profile.team_name,
+        team_slug: p.profile.team_slug,
+        active: p.active
+      }))
+    }, null, 2));
+    return;
+  }
+  if (data.type === "api_key") {
+    const team = data.team;
+    const permissions = data.permissions;
+    console.log(source_default.green("\u2713 Authenticated"));
+    console.log(`  Team:        ${team?.name ?? "unknown"}`);
+    console.log(`  Key type:    ${data.key_type}`);
+    console.log(`  Permissions: ${permissions.join(", ")}`);
+  } else {
+    const teams = data.teams;
+    console.log(source_default.green("\u2713 Authenticated"));
+    console.log(`  Email: ${data.email}`);
+    console.log(`  Teams: ${teams.map((t) => `${t.name} (${t.role})`).join(", ")}`);
+  }
+  const config = loadConfig();
+  if (config && Object.keys(config.teams).length > 0) {
+    const profiles = listProfiles(config);
+    console.log();
+    console.log("Configured profiles:");
+    for (const { teamId, profile, active } of profiles) {
+      const marker = active ? source_default.green("\u25CF") : " ";
+      const name = active ? source_default.bold(profile.team_name) : profile.team_name;
+      console.log(`  ${marker} ${name} (${profile.team_slug})    ${source_default.dim(teamId)}`);
+    }
+  }
+});
+
+// src/commands/switch.ts
+init_cjs_shims();
+var switchCommand = new Command("switch").description("Switch active team profile or list all profiles").argument("[team]", "Team ID, slug, or name to switch to").action(async (teamArg, _opts, cmd) => {
+  const globals = getGlobals(cmd);
+  const config = loadConfig();
+  if (!config || Object.keys(config.teams).length === 0) {
+    if (globals.format === "json") {
+      console.log(JSON.stringify({ error: "No team profiles configured" }));
+    } else {
+      console.error(source_default.red("No team profiles configured. Run `owlmetry auth verify` to add one."));
+    }
+    process.exit(1);
+  }
+  if (!teamArg) {
+    const profiles = listProfiles(config);
+    if (globals.format === "json") {
+      console.log(JSON.stringify(profiles.map((p) => ({
+        team_id: p.teamId,
+        team_name: p.profile.team_name,
+        team_slug: p.profile.team_slug,
+        active: p.active
+      })), null, 2));
+      return;
+    }
+    for (const { teamId: teamId2, profile: profile2, active } of profiles) {
+      const marker = active ? source_default.green("\u25CF") : " ";
+      const name = active ? source_default.bold(profile2.team_name) : profile2.team_name;
+      console.log(`  ${marker} ${name} (${profile2.team_slug})    ${source_default.dim(teamId2)}`);
+    }
+    return;
+  }
+  const { teamId, profile } = getActiveProfile(config, teamArg);
+  if (teamId === config.active_team) {
+    if (globals.format === "json") {
+      console.log(JSON.stringify({ team_id: teamId, team_name: profile.team_name, already_active: true }));
+    } else {
+      console.log(`Already on ${source_default.bold(profile.team_name)} (${profile.team_slug})`);
+    }
+    return;
+  }
+  config.active_team = teamId;
+  saveConfig(config);
+  if (globals.format === "json") {
+    console.log(JSON.stringify({ team_id: teamId, team_name: profile.team_name, team_slug: profile.team_slug }));
+  } else {
+    console.log(source_default.green(`\u2713 Switched to ${source_default.bold(profile.team_name)} (${profile.team_slug})`));
+  }
+});
+
 // src/index.ts
-var program2 = new Command().name("owlmetry").version("0.1.0").description("OwlMetry CLI \u2014 query metrics and manage your apps from the terminal").addOption(
+var program2 = new Command().name("owlmetry").version("0.1.2").description("OwlMetry CLI \u2014 query metrics and manage your apps from the terminal").addOption(
   new Option("--format <format>", "Output format").choices(["table", "json", "log"]).default("table")
-).option("--endpoint <url>", "OwlMetry server URL").option("--api-key <key>", "API key");
+).option("--endpoint <url>", "OwlMetry API server URL").option("--api-key <key>", "API key").option("--ingest-endpoint <url>", "OwlMetry ingest endpoint URL (for SDKs; defaults to API endpoint for self-hosted)").option("--team <name-or-id>", "Use a specific team profile for this command");
 program2.addCommand(authCommand);
 program2.addCommand(setupCommand);
 program2.addCommand(projectsCommand);
@@ -6991,6 +7188,8 @@ program2.addCommand(metricsCommand);
 program2.addCommand(funnelsCommand);
 program2.addCommand(auditLogCommand);
 program2.addCommand(skillsCommand);
+program2.addCommand(whoamiCommand);
+program2.addCommand(switchCommand);
 program2.parseAsync().catch((err) => {
   const format = program2.opts().format;
   const message = err instanceof Error ? err.message : String(err);

package/dist/skills/owlmetry-cli/SKILL.md

@@ -25,33 +25,82 @@ If everything is current or the remote is unreachable, continue silently.
 
 ## Setup
 
+Follow these steps in order. Skip any step that's already done.
+
+### Step 1 — Install the CLI
+
 **Prerequisites:** Node.js 20+
 
-**Install:**
 ```bash
 npm install -g @owlmetry/cli
 ```
 
-**Sign up / log in:**
+### Step 2 — Check authentication
+
 ```bash
-owlmetry auth send-code --email <user-email>
+owlmetry whoami --format json
 ```
-Ask the user for the 6-digit verification code that arrives by email, then:
+
+If this succeeds, authentication is already configured — skip to Step 3.
+
+If it fails (missing config or invalid key), run the auth flow:
+
+1. Ask the user for their email address.
+2. Send a verification code:
+   ```bash
+   owlmetry auth send-code --email <user-email>
+   ```
+3. Ask the user for the 6-digit code from their email.
+4. Verify and save credentials:
+   ```bash
+   owlmetry auth verify --email <user-email> --code <code> --format json
+   ```
+   This creates the user account and team (if new), generates an agent API key (`owl_agent_...`), and saves config to `~/.owlmetry/config.json`. Default API endpoint: `https://api.owlmetry.com`. Default ingest endpoint: `https://ingest.owlmetry.com`.
+
+**Multi-team setup**: If the user belongs to multiple teams, run `auth verify` once per team (using `--team-id` to select each team). Each team's key is stored as a separate profile. The last verified team becomes the active profile.
+
+**Switching teams**: Use `owlmetry switch` to list profiles or `owlmetry switch <name-or-slug>` to switch the active team. Use `--team <name-or-slug>` on any command to use a different team's key for a single command without switching.
+
+**Manual setup** (if the user already has an API key):
 ```bash
-owlmetry auth verify --email <user-email> --code <code> --format json
+owlmetry setup --endpoint <url> --api-key <key> [--ingest-endpoint <url>]
 ```
 
-- New users are auto-provisioned with a team, project, and backend app.
-- The response includes an agent API key (`owl_agent_...`), team ID, project ID, and app details.
-- Config is saved to `~/.owlmetry/config.json`.
-- Default endpoint: `https://api.owlmetry.com`
+### Step 3 — Create project and app
 
-If the user already has a config file (`~/.owlmetry/config.json`), they're already set up — skip auth.
+After authentication, set up the resources the SDK needs. Check if any projects already exist:
 
-**Manual setup** (if the user already has an API key):
 ```bash
-owlmetry setup --endpoint <url> --api-key <key>
+owlmetry projects --format json
+```
+
+If the user already has a project and app, skip to SDK integration.
+
+**Create a project** — infer a good name from the user's repository or directory name:
+```bash
+owlmetry projects create --name "<ProjectName>" --slug "<project-slug>" --format json
 ```
+Save the returned `id` — you need it for the next command.
+
+**Create an app** — choose the platform based on the project type:
+- Swift/SwiftUI → `apple`
+- Kotlin/Android → `android`
+- Web frontend → `web`
+- Node.js/backend → `backend`
+
+```bash
+owlmetry apps create --project-id <project-id> --name "<AppName>" --platform <platform> [--bundle-id <bundle-id>] --format json
+```
+- `--bundle-id` is required for apple/android/web (e.g., `com.example.myapp`), omitted for backend.
+- The response includes a `client_key` (`owl_client_...`) — this is the SDK API key for event ingestion. Save it.
+
+### Step 4 — Integrate the SDK
+
+Use the `client_key` from Step 3 to configure the appropriate SDK:
+- **Node.js projects** → follow the `owlmetry-node` skill file
+- **Swift/iOS projects** → follow the `owlmetry-swift` skill file
+
+Pass the **ingest endpoint** and client key to the SDK's `configure()` call. Read `~/.owlmetry/config.json` for the `ingest_endpoint` value (set during auth). For the hosted platform it's `https://ingest.owlmetry.com`. For self-hosted it defaults to the API endpoint.
 
 ## Resource Hierarchy
 
@@ -197,7 +246,10 @@ owlmetry audit-log list --team <id> [--resource-type <type>] [--resource-id <id>
 ## Key Notes
 
 - Always use `--format json` when parsing output programmatically.
-- **Global flags** available on all commands: `--endpoint <url>`, `--api-key <key>`, `--format <format>`
+- **Global flags** available on all commands: `--endpoint <url>`, `--api-key <key>`, `--ingest-endpoint <url>`, `--team <name-or-id>`, `--format <format>`
+- **Team profiles**: Config stores multiple team profiles keyed by team ID. `owlmetry switch` lists/switches the active profile. `--team` flag on any command uses a specific team's key without switching the active profile.
+- **Two endpoints**: `endpoint` is the API server (for CLI/agent queries). `ingest_endpoint` is where SDKs send events. Both are saved in `~/.owlmetry/config.json`. For the hosted platform: `api.owlmetry.com` and `ingest.owlmetry.com`. For self-hosted: ingest defaults to the same as the API endpoint.
+- **Config format**: `~/.owlmetry/config.json` stores `endpoint`, `ingest_endpoint`, `active_team` (team ID), and `teams` (a map of team ID → `{ api_key, team_name, team_slug }`).
 - **Agent keys** (`owl_agent_...`) are for CLI queries. **Client keys** (`owl_client_...`) are for SDK event ingestion.
 - **Time format:** relative (`1h`, `30m`, `7d`) or ISO 8601 (`2026-03-20T00:00:00Z`). Relative times go backwards from now — `1h` means "the last hour", `7d` means "the last 7 days".
 - **Data mode:** `production` (default), `debug`, or `all` — filters events by their debug flag. SDKs auto-detect debug mode (DEBUG builds on iOS, `NODE_ENV !== "production"` on Node). Use `debug` mode during development to see test events; use `production` (the default) for real analytics.
@@ -207,10 +259,20 @@ owlmetry audit-log list --team <id> [--resource-type <type>] [--resource-id <id>
 
 A typical end-to-end flow for adding OwlMetry to a new project:
 
-1. **Sign up**: `owlmetry auth send-code` → verify code → auto-provisioned with team, project, and backend app
-2. **Create apps**: `owlmetry apps create --platform apple --bundle-id com.example.myapp` (and/or android, web, backend)
-3. **Note the client key**: from the app creation response — pass this to the SDK
-4. **Instrument the app**: Add the Swift or Node SDK, configure with the endpoint and client key, add logging calls
-5. **Define metrics**: `owlmetry metrics create --slug photo-upload --lifecycle` for operations you want to track with duration
-6. **Define funnels**: `owlmetry funnels create --slug onboarding --steps '[...]'` for multi-step flows you want to measure conversion on
-7. **Query data**: Use `owlmetry events`, `owlmetry metrics query`, and `owlmetry funnels query` to analyze behavior
+1. **Sign up** (CLI): `owlmetry auth send-code` → verify code → team created, config saved
+2. **Create a project** (CLI): `owlmetry projects create --name "..." --slug "..." --format json`
+3. **Create apps** (CLI): `owlmetry apps create --platform apple --bundle-id com.example.myapp` (and/or android, web, backend)
+4. **Note the client key**: from the app creation response — pass this to the SDK
+5. **Integrate the SDK** (switch to `/owlmetry-swift` or `/owlmetry-node` skill): Add the SDK dependency, configure with `ingest_endpoint` and client key, verify the project builds
+
+After setup, the SDK skill will prompt the user to choose which instrumentation to start with. The three areas and what's needed:
+
+| Area | CLI setup needed? | SDK skill |
+|------|-------------------|-----------|
+| **Event & error logging** | No — just add SDK calls | `Owl.info()`, `Owl.error()`, `Owl.warn()`, `Owl.debug()` |
+| **Structured metrics** | Yes — `owlmetry metrics create` for each metric slug | `Owl.startOperation()`, `Owl.recordMetric()` |
+| **Funnel tracking** | Yes — `owlmetry funnels create` with steps JSON | `Owl.track("step-name")` |
+
+For metrics and funnels, the CLI defines **what** to track (server-side definitions), and the SDK implements **where** to track it (code instrumentation). The definition must exist before the SDK emits events for that slug.
+
+6. **Query data** (CLI): Use `owlmetry events`, `owlmetry metrics query`, and `owlmetry funnels query` to analyze behavior

package/dist/skills/owlmetry-node/SKILL.md

@@ -23,13 +23,9 @@ Run these checks silently. Only inform the user if updates are available.
 
 ## Prerequisite
 
-You need an OwlMetry endpoint URL and a `client_key` (starts with `owl_client_...`) for an app with `platform: backend`.
+You need an **ingest endpoint** and a **client key** (`owl_client_...`) for a backend app. Both come from the CLI setup flow.
 
-If the user doesn't have these yet, invoke `/owlmetry-cli` first to:
-1. Sign up or log in
-2. Create a project (if needed)
-3. Create an app with `--platform backend` (no `--bundle-id` needed)
-4. Note the `client_key` from the app creation response
+If the user doesn't have these yet, follow the `/owlmetry-cli` skill first — it handles sign-up, project creation, and app creation. The ingest endpoint is saved to `~/.owlmetry/config.json` (`ingest_endpoint` field) and the client key is returned when creating an app.
 
 ## Install
 
@@ -61,6 +57,16 @@ Owl.configure({
 - Generates a fresh `sessionId` (UUID) on each `configure()` call
 - Registers a `beforeExit` handler to auto-flush on graceful shutdown
 
+## Next Steps — Codebase Instrumentation
+
+Once `Owl.configure()` is in place and the project builds, **stop and ask the user** which area they'd like to instrument first. Present these three options:
+
+1. **Event & error logging** — Audit the codebase for request handlers, error paths, background jobs, and key operations. Add `Owl.info()`, `Owl.warn()`, `Owl.error()` calls at meaningful points throughout the service. This is SDK-only — no CLI setup required beyond what's already done.
+2. **Structured metrics** — Identify operations worth measuring (API response times, database queries, external service calls, etc.). Add `Owl.startOperation()` / `Owl.recordMetric()` to track durations and success rates. **Requires CLI first:** each metric slug must be defined on the server via `owlmetry metrics create` (use the `/owlmetry-cli` skill) before the SDK can emit events for it.
+3. **Funnel tracking** — Identify server-side user journeys (sign-up flow, payment processing, onboarding steps). Add `Owl.track()` calls at each step to measure drop-off. **Requires CLI first:** the funnel definition (with steps and event filters) must be created via `owlmetry funnels create` (use the `/owlmetry-cli` skill) before tracking makes sense.
+
+Wait for the user to choose before proceeding. For whichever option they pick, do a thorough audit of the entire codebase to find all relevant locations, then present a summary of proposed changes before making any edits.
+
 ## Buffering and Delivery
 
 The SDK buffers events in memory and sends them to the server in batches. Understanding how buffering works helps you avoid lost events:
@@ -313,3 +319,29 @@ fastify.post('/api/process', async (request, reply) => {
   return { ok: true };
 });
 ```
+
+## Instrumentation Strategy
+
+When instrumenting a backend service, follow this priority:
+
+**Always instrument (events — no CLI setup needed):**
+- Server startup and shutdown (`info`)
+- Request handling: key route hits, responses sent (`info` with method/path/status)
+- Errors and failures: catch blocks, unhandled rejections, external API failures (`error`)
+- Authentication events: login, logout, token refresh (`info`)
+- Core business actions: order placed, payment processed, email sent (`info`)
+- Background jobs: started, completed, failed (`info`/`error`)
+
+**Instrument when relevant (metrics — requires CLI `owlmetry metrics create` first):**
+- Lifecycle metrics for operations where duration matters: API response time, database queries, external service calls, file processing
+- Single-shot metrics for point-in-time values: queue depth, cache hit rate, active connections
+
+**Instrument when relevant (funnels — requires CLI `owlmetry funnels create` first):**
+- Multi-step server-side flows you want to measure conversion on: signup pipeline, payment processing, onboarding sequence
+- Always use `Owl.withUser()` for funnel events — funnel analytics require user IDs to calculate conversion
+
+**What NOT to instrument:**
+- PII (emails, passwords, tokens, IP addresses)
+- High-frequency health checks or heartbeats
+- Every database query (instrument categories, not every call)
+- Sensitive business data (payment amounts, account balances)

package/dist/skills/owlmetry-swift/SKILL.md

@@ -23,13 +23,9 @@ Run these checks silently. Only inform the user if updates are available.
 
 ## Prerequisite
 
-You need an OwlMetry endpoint URL and a `client_key` (starts with `owl_client_...`) for an app with `platform: apple`.
+You need an **ingest endpoint** and a **client key** (`owl_client_...`) for an Apple-platform app. Both come from the CLI setup flow.
 
-If the user doesn't have these yet, invoke `/owlmetry-cli` first to:
-1. Sign up or log in
-2. Create a project (if needed)
-3. Create an app with `--platform apple --bundle-id <bundle-id>`
-4. Note the `client_key` from the app creation response
+If the user doesn't have these yet, follow the `/owlmetry-cli` skill first — it handles sign-up, project creation, and app creation. The ingest endpoint is saved to `~/.owlmetry/config.json` (`ingest_endpoint` field) and the client key is returned when creating an app.
 
 ## Add Swift Package
 
@@ -50,6 +46,26 @@ Add to your target:
 
 **Minimum platforms:** iOS 16.0, macOS 13.0. Zero external dependencies.
 
+## Verify Package Integration
+
+After adding the package, build the project to verify the dependency resolves and `import OwlMetry` compiles. Do not proceed with configuration until the build succeeds.
+
+If the build fails with a "No such module 'OwlMetry'" error, ask the user to add the package manually in Xcode:
+
+1. Open the `.xcodeproj` or `.xcworkspace` in Xcode
+2. Select the project in the navigator (blue icon at the top)
+3. Select the app target under "Targets"
+4. Go to the "General" tab
+5. Scroll to "Frameworks, Libraries, and Embedded Content"
+6. Click the **+** button
+7. Click "Add Other…" > "Add Package Dependency…"
+8. Enter the URL: `https://github.com/Jasonvdb/owlmetry.git`
+9. Set "Dependency Rule" to **Branch** → `main`
+10. Click "Add Package"
+11. Select the **OwlMetry** library and click "Add Package"
+
+Once the user confirms the package is added, retry the build to verify, then proceed with configuration.
+
 ## Configure
 
 Configuration must happen once, before any other `Owl` calls — typically in your `@main` App init or AppDelegate `didFinishLaunching`. Each `configure()` call generates a fresh `session_id` (UUID) that groups all subsequent events together. This means each app launch gets its own session, making it easy to see everything a user did in a single sitting.
@@ -81,6 +97,16 @@ struct MyApp: App {
 
 Auto-detects: bundle ID, debug mode (`#if DEBUG`). Auto-generates: session ID (fresh each launch).
 
+## Next Steps — Codebase Instrumentation
+
+Once `Owl.configure()` is in place and the project builds, **stop and ask the user** which area they'd like to instrument first. Present these three options:
+
+1. **Event & error logging** — Audit the codebase for user actions, screen views, error handling, and key flows. Add `Owl.info()`, `Owl.warn()`, `Owl.error()` calls at meaningful points. This is SDK-only — no CLI setup required beyond what's already done.
+2. **Structured metrics** — Identify operations worth measuring (network requests, data loading, image processing, etc.). Add `Owl.startOperation()` / `Owl.recordMetric()` to track durations and success rates. **Requires CLI first:** each metric slug must be defined on the server via `owlmetry metrics create` (use the `/owlmetry-cli` skill) before the SDK can emit events for it.
+3. **Funnel tracking** — Identify user journeys (onboarding, checkout, key conversions). Add `Owl.track()` calls at each step to measure drop-off. **Requires CLI first:** the funnel definition (with steps and event filters) must be created via `owlmetry funnels create` (use the `/owlmetry-cli` skill) before tracking makes sense.
+
+Wait for the user to choose before proceeding. For whichever option they pick, do a thorough audit of the entire codebase to find all relevant locations, then present a summary of proposed changes before making any edits.
+
 ## Log Events
 
 Events are the core unit of data in OwlMetry. Use the four log levels to capture different kinds of information:
@@ -224,16 +250,19 @@ Owl.clearExperiments()
 
 When instrumenting a new app, follow this priority:
 
-**Always instrument:**
+**Always instrument (events — no CLI setup needed):**
 - App launch / cold start (`info` in `init()` or `didFinishLaunching`)
 - Key screen views (`info` with `screenName` in `onAppear`)
 - Authentication events (login, logout, signup)
 - Errors and failures (`error` in `catch` blocks, error handlers)
 - Core business actions (purchase, share, create, delete)
 
-**Instrument when relevant:**
-- Funnel steps for multi-step flows you want to optimize
-- Lifecycle metrics for operations where duration matters (uploads, loads, syncs)
+**Instrument when relevant (metrics — requires CLI `owlmetry metrics create` first):**
+- Lifecycle metrics for operations where duration matters: image uploads, API calls, data syncs, video encoding
+- Single-shot metrics for point-in-time values: app cold-start time, memory usage, items in cart
+
+**Instrument when relevant (funnels — requires CLI `owlmetry funnels create` first):**
+- Multi-step flows you want to measure conversion on: onboarding, checkout, activation
 - A/B experiments when testing alternative UI or flows
 
 **Where to place calls:**

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@owlmetry/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "OwlMetry CLI — manage projects, apps, metrics, funnels, and events from the terminal. Includes AI skill files for agent-assisted development.",
   "type": "module",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Jasonvdb/owlmetry.git",
+    "url": "git+https://github.com/Jasonvdb/owlmetry.git",
     "directory": "apps/cli"
   },
   "homepage": "https://owlmetry.com",