@owlmetry/cli 0.1.3 → 0.1.7

package/dist/index.cjs

@@ -7183,7 +7183,7 @@ var switchCommand = new Command("switch").description("Switch active team profil
 });
 
 // src/index.ts
-var program2 = new Command().name("owlmetry").version("0.1.3").description("OwlMetry CLI \u2014 query metrics and manage your apps from the terminal").addOption(
+var program2 = new Command().name("owlmetry").version("0.1.7").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 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);

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

@@ -1,10 +1,12 @@
 ---
 name: owlmetry-cli
-version: 0.1.3
+version: 0.1.7
 description: >-
   Install the OwlMetry CLI, sign up, and manage projects, apps, metrics,
   funnels, and events. Use when adding OwlMetry to a project, querying
   analytics, or when another OwlMetry skill needs CLI setup as a prerequisite.
+  IMPORTANT: You MUST load this skill before running ANY `owlmetry` CLI
+  command. The CLI has non-obvious subcommand syntax and flags — do not guess.
 allowed-tools: Bash
 ---
 
@@ -14,11 +16,13 @@ OwlMetry is a self-hosted analytics platform for mobile and backend apps. It cap
 
 The **CLI** is the management and query tool — it does not ingest events. You use it to create projects and apps, define metrics and funnels, query event data, and view analytics. SDKs handle event ingestion using client keys (`owl_client_...`). The CLI uses agent keys (`owl_agent_...`) for reading data and managing resources.
 
+> **Do not guess CLI syntax.** The `owlmetry` command has specific subcommand patterns (e.g., `owlmetry apps` not `owlmetry apps list`, flags like `--format json` not `--message`). Always reference the command documentation in this skill file before running a command. If you haven't loaded this skill yet, load it first.
+
 ## Version Check
 
 Run these checks silently. Only inform the user if updates are available.
 
-1. **Skill version**: `curl -sf https://raw.githubusercontent.com/Jasonvdb/owlmetry/main/skills/owlmetry-cli/SKILL.md | head -5` — compare the `version:` field to `0.1.0`. If newer, ask the user if they want to update the local skill file.
+1. **Skill version**: `curl -sf https://raw.githubusercontent.com/Jasonvdb/owlmetry/main/skills/owlmetry-cli/SKILL.md | head -5` — compare the remote `version:` field to this file's `version:` frontmatter above. If the remote version is newer, ask the user if they want to update the local skill file.
 2. **CLI version** (if installed): compare `owlmetry --version` to `npm view @owlmetry/cli version 2>/dev/null`. If a newer version exists, offer `npm install -g @owlmetry/cli@latest`.
 
 If everything is current or the remote is unreachable, continue silently.

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

@@ -1,6 +1,6 @@
 ---
 name: owlmetry-node
-version: 0.1.3
+version: 0.1.7
 description: >-
   Integrate the OwlMetry Node.js SDK into a backend service for server-side
   analytics, event tracking, metrics, funnels, and A/B experiments. Use when
@@ -18,7 +18,7 @@ The SDK has zero runtime dependencies. All calls are non-blocking — events are
 
 Run these checks silently. Only inform the user if updates are available.
 
-1. **Skill version**: `curl -sf https://raw.githubusercontent.com/Jasonvdb/owlmetry/main/skills/owlmetry-node/SKILL.md | head -5` — compare the `version:` field to `0.1.0`. If newer, ask the user if they want to update.
+1. **Skill version**: `curl -sf https://raw.githubusercontent.com/Jasonvdb/owlmetry/main/skills/owlmetry-node/SKILL.md | head -5` — compare the remote `version:` field to this file's `version:` frontmatter above. If the remote version is newer, ask the user if they want to update.
 2. **SDK version**: `npm ls @owlmetry/node --json 2>/dev/null` for current version, `npm view @owlmetry/node version 2>/dev/null` for latest. If newer, offer `npm install @owlmetry/node@latest`.
 
 ## Prerequisite
@@ -27,6 +27,8 @@ You need an **ingest endpoint** and a **client key** (`owl_client_...`) for a ba
 
 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.
 
+> **Any time you need to run an `owlmetry` CLI command** (querying events, creating metrics/funnels, listing apps, etc.), **load the `/owlmetry-cli` skill first**. Do not guess CLI syntax — it has non-obvious subcommand patterns and flags.
+
 ## Install
 
 ```bash
@@ -37,6 +39,8 @@ Zero runtime dependencies. Node.js 20+. ESM only.
 
 ## Configure
 
+Place `Owl.configure()` in the **main entry point** of your service — the root `index.ts`, `server.ts`, or `app.ts` file where your server starts. It must run once at process startup, before any other `Owl` calls. Do **not** put it in a helper/utility file — it should be alongside your other top-level initialization (e.g., `express()`, `Fastify()`, Firebase `setGlobalOptions`).
+
 ```typescript
 import { Owl } from '@owlmetry/node';
 
@@ -57,6 +61,27 @@ Owl.configure({
 - Generates a fresh `sessionId` (UUID) on each `configure()` call
 - Registers a `beforeExit` handler to auto-flush on graceful shutdown
 
+**Serverless (Firebase Cloud Functions, AWS Lambda, Vercel):** After adding `Owl.configure()`, also wrap your exported handler functions with `Owl.wrapHandler()` to guarantee events are flushed before the runtime freezes. This is essential boilerplate for serverless — without it, buffered events are lost:
+
+```typescript
+// AWS Lambda / generic serverless:
+export const handler = Owl.wrapHandler(async (event, context) => { ... });
+
+// Firebase Cloud Functions v2:
+// IMPORTANT: Explicitly type the request parameter — TypeScript cannot infer
+// the CallableRequest type through wrapHandler's generics.
+import { onCall, type CallableRequest } from 'firebase-functions/v2/https';
+
+export const myFunction = onCall(
+  Owl.wrapHandler(async (request: CallableRequest) => {
+    const { data, auth } = request;  // works — TypeScript knows the type
+    // ...
+  })
+);
+```
+
+**TypeScript note:** `wrapHandler()` uses generic rest parameters (`<TArgs extends unknown[]>`), which means TypeScript sometimes infers handler parameters as `unknown` when the outer function (like Firebase's `onCall`) expects a specific callback type. If you see type errors like `Property 'data' does not exist on type 'unknown'`, explicitly annotate the handler's parameters (e.g., `request: CallableRequest`, `event: APIGatewayEvent`).
+
 ## Next Steps — Codebase Instrumentation
 
 Once `Owl.configure()` is in place and the project builds successfully, **you MUST stop here and ask the user** which area they'd like to instrument first — even if the user's original prompt asked you to "instrument the app." Do not proceed with any code changes until the user chooses. Present these three options:
@@ -85,16 +110,21 @@ Events are the core data unit. Use the four log levels to capture different kind
 
 - **`info`** — normal operations: server started, request handled, job completed, user action processed.
 - **`debug`** — verbose detail for development: cache lookups, query plans, config loading, intermediate state.
-- **`warn`** — recoverable problems: slow queries, rate limits approaching, fallback paths, deprecated API usage.
-- **`error`** — failures: database connection errors, external API failures, unhandled rejections, missing resources.
+- **`warn`** — something didn't go as expected but the process can continue: failed validation, precondition checks that fail, slow queries, rate limits approaching, fallback paths, deprecated API usage, missing optional config.
+- **`error`** — a caught exception or hard failure inside a `try`/`catch`: database connection errors, external API timeouts, unhandled rejections, file system errors. Reserve for actual thrown errors, not for anticipated validation outcomes.
 
 Choose **message strings** that are specific and searchable. Prefer `"Payment processing failed"` over `"error occurred"`. Use attributes for structured data you'll filter on later.
 
 ```typescript
 Owl.info('Server started', { port: 4000 });
 Owl.debug('Cache miss', { key: 'user:123' });
-Owl.warn('Slow query', { duration_ms: 2500, table: 'events' });
-Owl.error('Database connection failed', { host: 'db.example.com' });
+Owl.warn('Invalid request payload', { field: 'email', reason: 'missing' });
+
+try {
+  await db.connect();
+} catch (err) {
+  Owl.error('Database connection failed', { host: 'db.example.com', error: String(err) });
+}
 ```
 
 All methods: `Owl.info/debug/warn/error(message: string, attrs?: Record<string, unknown>)`.
@@ -106,7 +136,12 @@ Source module (file:line) is auto-captured from the call stack.
 Owl.info('Request handled', { method: 'POST', path: '/api/orders', status: 201 });
 Owl.info('Background job completed', { job: 'send-emails', processed: 150 });
 Owl.warn('Rate limit approaching', { current: 95, limit: 100, client_id: 'abc' });
-Owl.error('External API timeout', { service: 'stripe', endpoint: '/charges', timeout_ms: 10000 });
+
+try {
+  await stripe.charges.create(params);
+} catch (err) {
+  Owl.error('Stripe charge failed', { endpoint: '/charges', error: String(err) });
+}
 ```
 
 ## Per-Request User Scoping
@@ -327,7 +362,8 @@ 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`)
+- Caught exceptions: catch blocks, unhandled rejections, external API failures (`error`)
+- Validation failures and pre-checks: bad input, missing optional config, rate limits (`warn`)
 - Authentication events: login, logout, token refresh (`info`)
 - Core business actions: order placed, payment processed, email sent (`info`)
 - Background jobs: started, completed, failed (`info`/`error`)

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

@@ -1,6 +1,6 @@
 ---
 name: owlmetry-swift
-version: 0.1.3
+version: 0.1.7
 description: >-
   Integrate the OwlMetry Swift SDK into an iOS or macOS app for analytics,
   event tracking, metrics, funnels, and A/B experiments. Use when
@@ -18,7 +18,7 @@ The SDK is a static `Owl` enum with no external dependencies. All calls are non-
 
 Run these checks silently. Only inform the user if updates are available.
 
-1. **Skill version**: `curl -sf https://raw.githubusercontent.com/Jasonvdb/owlmetry/main/skills/owlmetry-swift/SKILL.md | head -5` — compare the `version:` field to `0.1.0`. If newer, ask the user if they want to update.
+1. **Skill version**: `curl -sf https://raw.githubusercontent.com/Jasonvdb/owlmetry/main/skills/owlmetry-swift/SKILL.md | head -5` — compare the remote `version:` field to this file's `version:` frontmatter above. If the remote version is newer, ask the user if they want to update.
 2. **SDK version**: Read `Package.resolved` for the current resolved revision, then compare against `curl -sf https://api.github.com/repos/Jasonvdb/owlmetry/releases/latest | jq -r .tag_name`. If newer, inform the user.
 
 ## Prerequisite
@@ -27,9 +27,16 @@ You need an **ingest endpoint** and a **client key** (`owl_client_...`) for an A
 
 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.
 
+> **Any time you need to run an `owlmetry` CLI command** (querying events, creating metrics/funnels, listing apps, etc.), **load the `/owlmetry-cli` skill first**. Do not guess CLI syntax — it has non-obvious subcommand patterns and flags.
+
 ## Add Swift Package
 
-**Swift Package Manager (Package.swift):**
+**Minimum platforms:** iOS 16.0, macOS 13.0. Zero external dependencies.
+
+### Option A — Package.swift projects
+
+If the project has a `Package.swift`, add the dependency there:
+
 ```swift
 dependencies: [
     .package(url: "https://github.com/Jasonvdb/owlmetry.git", branch: "main")
@@ -42,33 +49,35 @@ Add to your target:
 ])
 ```
 
-**Xcode:** File > Add Package Dependencies > enter `https://github.com/Jasonvdb/owlmetry.git`, select branch `main`, add `OwlMetry` to your target.
+Then run `swift package resolve` to fetch the dependency.
 
-**Minimum platforms:** iOS 16.0, macOS 13.0. Zero external dependencies.
+### Option B — Xcode projects (.xcodeproj)
 
-## Verify Package Integration
+For `.xcodeproj`-based projects with no `Package.swift`, add the OwlMetry Swift package by editing `<Project>.xcodeproj/project.pbxproj` directly to add a remote Swift package reference for `https://github.com/Jasonvdb/owlmetry.git` (branch: `main`, product: `OwlMetry`). Do not ask the user to add it manually in Xcode.
 
-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.
+### Option C — Ask the user (last resort)
 
-If the build fails with a "No such module 'OwlMetry'" error, ask the user to add the package manually in Xcode:
+If pbxproj editing fails or the project structure is too complex, ask the user to add the package 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"
+1. File > Add Package Dependencies
+2. Enter URL: `https://github.com/Jasonvdb/owlmetry.git`
+3. Set rule to **Branch** > `main`
+4. Add **OwlMetry** to the app target
+
+## Verify Package Integration
+
+After adding the package, resolve dependencies and build:
+
+```bash
+xcodebuild -resolvePackageDependencies -project <path>.xcodeproj -quiet
+xcodebuild -project <path>.xcodeproj -scheme <SchemeName> -destination 'platform=iOS Simulator,name=iPhone 16' build -quiet
+```
 
-Once the user confirms the package is added, retry the build to verify, then proceed with configuration.
+If the build succeeds, proceed with configuration. The "No such module 'OwlMetry'" warning in editors (SourceKit) is expected and resolves during a real `xcodebuild`.
 
 ## 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.
+Configuration must happen once, as early as possible — in the `@main` App `init()` or AppDelegate `didFinishLaunching`. **Do not defer it** to a later point (e.g., after async setup or user consent). The SDK measures app launch time (`_launch_ms`) from process start to the `configure()` call, so placing it early gives an accurate cold-start metric. It also ensures no events are dropped before configuration. Each `configure()` call generates a fresh `session_id` (UUID) that groups all subsequent events together.
 
 ```swift
 import OwlMetry
@@ -94,35 +103,119 @@ struct MyApp: App {
 - `apiKey: String` — client key, must start with `owl_client_` (required)
 - `flushOnBackground: Bool` — auto-flush when app backgrounds (default: `true`)
 - `compressionEnabled: Bool` — gzip request bodies (default: `true`)
+- `networkTrackingEnabled: Bool` — auto-track URLSession HTTP requests (default: `true`)
 
 Auto-detects: bundle ID, debug mode (`#if DEBUG`). Auto-generates: session ID (fresh each launch).
 
+## User Identity (set up during initial configuration)
+
+After adding `Owl.configure()`, find where the app handles authentication and add `Owl.setUser()` / `Owl.clearUser()`. This is part of the basic setup — do it now, before moving on to instrumentation.
+
+Look for the auth state change handler (e.g., Firebase Auth listener, login/logout methods) and add:
+
+```swift
+// After successful login — claims all previous anonymous events for this user
+Owl.setUser(userId)
+
+// On logout — reverts to anonymous tracking
+Owl.clearUser()
+```
+
+**Where to find it:** Search for login/logout methods, auth state listeners, or session management code. Look for patterns like setting a user ID on other services (crash reporting, analytics), storing auth tokens, or clearing user state. Place `Owl.setUser()` right after the user ID becomes available. Place `Owl.clearUser()` in the sign-out/logout handler.
+
+The SDK automatically flushes buffered events before claiming identity, so anonymous events from before login are retroactively linked to the user.
+
 ## Next Steps — Codebase Instrumentation
 
-Once `Owl.configure()` is in place and the project builds successfully, **you MUST stop here and ask the user** which area they'd like to instrument first — even if the user's original prompt asked you to "instrument the app." Do not proceed with any code changes until the user chooses. Present these three options:
+Once `Owl.configure()` is in place and the project builds successfully, **you MUST stop here and ask the user** which area they'd like to instrument first — even if the user's original prompt asked you to "instrument the app." Do not proceed with any code changes until the user chooses. Present these 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.
+1. **Screen tracking** — Add `.owlScreen("ScreenName")` to every distinct screen in the app. This is the quickest win — automatic screen view and time-on-screen tracking with a single modifier per screen. No CLI setup needed.
+2. **Event & error logging** — Audit the codebase for user actions, 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.
+3. **Structured metrics** — Identify operations worth measuring (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.
+4. **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.
 
 After the user chooses, do a thorough audit of the entire codebase to find all relevant locations, then present a summary of proposed changes before making any edits.
 
+## Screen Tracking (`.owlScreen()`)
+
+The SDK provides a SwiftUI view modifier that automatically tracks screen appearances and time-on-screen with zero manual event calls.
+
+```swift
+struct HomeView: View {
+    var body: some View {
+        VStack { ... }
+            .owlScreen("Home")
+    }
+}
+
+struct SettingsView: View {
+    var body: some View {
+        Form { ... }
+            .owlScreen("Settings")
+    }
+}
+```
+
+**What it does automatically:**
+- On appear: emits `sdk:screen_appeared` (info level) with `screenName` set — included in production data
+- On disappear: emits `sdk:screen_disappeared` (debug level) with `screenName` set and `_duration_ms` attribute — only visible in dev data mode
+
+**Where to place it:** Attach `.owlScreen("ScreenName")` to the outermost view of each screen — typically on the `NavigationStack`, `Form`, `ScrollView`, or root `VStack`. Use it on every distinct screen in the app. Choose names that are short, readable, and consistent (e.g., `"Home"`, `"Settings"`, `"Profile"`, `"Checkout"`).
+
+**Prefer `.owlScreen()` over manual `Owl.info()` for screen views** — it handles both appear and disappear with duration tracking. Use manual `Owl.info()` with `screenName:` only for events within a screen (button taps, state changes), not for screen appearances themselves.
+
+## Network Request Tracking
+
+The SDK automatically tracks all URLSession HTTP requests made via completion handler APIs. This is **enabled by default** — no code needed beyond `Owl.configure()`. To disable:
+
+```swift
+try Owl.configure(
+    endpoint: "https://ingest.owlmetry.com",
+    apiKey: "owl_client_...",
+    networkTrackingEnabled: false
+)
+```
+
+**What it captures automatically:**
+- `_http_method` — GET, POST, etc.
+- `_http_url` — sanitized URL (scheme + host + path only, query params stripped for privacy)
+- `_http_status` — response status code
+- `_http_duration_ms` — request duration in milliseconds
+- `_http_response_size` — response body size in bytes
+- `_http_error` — error description (failures only)
+
+**Log levels:** `.info` for 2xx/3xx responses, `.warn` for 4xx/5xx, `.error` for network failures (no response).
+
+**Safety:** The SDK's own requests to the OwlMetry ingest endpoint are automatically filtered out. Query parameters are stripped from URLs to prevent accidental logging of tokens or user IDs.
+
+**Coverage:** Tracks requests made with `URLSession.dataTask(with:completionHandler:)` (both URL and URLRequest overloads). Delegate-based and async/await requests are not tracked in this version.
+
 ## Log Events
 
 Events are the core unit of data in OwlMetry. Use the four log levels to capture different kinds of information:
 
 - **`info`** — normal operations worth recording: screen views, user actions, feature usage, successful completions. This is your default level.
 - **`debug`** — verbose detail useful only during development: cache hits, state transitions, intermediate values. These are filtered out in production data mode.
-- **`warn`** — something unexpected that the app recovered from: slow responses, fallback paths taken, retries needed.
-- **`error`** — something failed: network errors, parse failures, missing data, caught exceptions.
+- **`warn`** — something didn't go as expected but the app can continue: failed validation, precondition checks that fail, slow responses, fallback paths taken, deprecated API usage, missing optional data.
+- **`error`** — a caught exception or hard failure inside a `do`/`catch` block: network errors, JSON decode failures, file I/O errors, keychain access failures. Reserve for actual thrown errors, not for anticipated validation outcomes.
 
 Choose **message strings** that are specific and searchable. Prefer `"Failed to load profile image"` over `"error"`. Use `screenName` to tie events to where they happened in the UI. Use `customAttributes` for structured data you'll want to filter or search on later.
 
 ```swift
+// In a screen context — pass screenName to tie the event to the screen
 Owl.info("User opened settings", screenName: "SettingsView")
 Owl.debug("Cache hit", screenName: "HomeView", customAttributes: ["key": "user_prefs"])
-Owl.warn("Slow network response", customAttributes: ["latency_ms": "1200"])
-Owl.error("Failed to load profile", screenName: "ProfileView")
+Owl.warn("Invalid email format", screenName: "SignUpView", customAttributes: ["input": email])
+
+do {
+    let profile = try await api.loadProfile(id: userId)
+} catch {
+    Owl.error("Failed to load profile", screenName: "ProfileView", customAttributes: ["error": "\(error)"])
+}
+
+// Outside a screen context — omit screenName entirely
+Owl.info("Background sync completed", customAttributes: ["items": "\(count)"])
+Owl.error("Keychain write failed", customAttributes: ["error": "\(error)"])
 ```
 
 All logging methods share the same signature:
@@ -130,6 +223,8 @@ All logging methods share the same signature:
 Owl.info(_ message: String, screenName: String? = nil, customAttributes: [String: String]? = nil)
 ```
 
+**`screenName` is optional.** Only pass it when the event originates from a specific screen in the UI (e.g., a button tap handler inside a view). **Do NOT pass `screenName`** when logging from utility functions, services, managers, network layers, background tasks, or anywhere that isn't directly tied to a visible screen. Passing a fabricated or guessed screen name is worse than omitting it — it pollutes screen-level analytics.
+
 Source file, function, and line are auto-captured.
 
 **Avoid logging PII** (emails, phone numbers, passwords) or high-frequency events (every frame, every scroll position). Focus on actions and outcomes.
@@ -251,10 +346,11 @@ Owl.clearExperiments()
 When instrumenting a new app, follow this priority:
 
 **Always instrument (events — no CLI setup needed):**
+- Screen views (`.owlScreen("ScreenName")` on every distinct screen)
 - 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)
+- Caught exceptions (`error` in `catch` blocks, error handlers)
+- Validation failures and pre-checks (`warn` for bad input, missing optional data, fallback paths)
 - Core business actions (purchase, share, create, delete)
 
 **Instrument when relevant (metrics — requires CLI `owlmetry metrics create` first):**
@@ -266,9 +362,10 @@ When instrumenting a new app, follow this priority:
 - A/B experiments when testing alternative UI or flows
 
 **Where to place calls:**
-- Screen views: `.onAppear` modifiers in SwiftUI, `viewDidAppear` in UIKit
-- User actions: button action handlers, gesture callbacks
-- Errors: `catch` blocks, `Result.failure` handlers
+- Screen views: `.owlScreen("Name")` on the outermost view of each screen (SwiftUI), `viewDidAppear` in UIKit
+- User actions: button action handlers, gesture callbacks — pass `screenName` since you know which screen the user is on
+- Errors: `catch` blocks, `Result.failure` handlers — pass `screenName` only if the error is caught inside a view; omit it if caught in a service, manager, or utility
+- Services, utilities, background tasks: log freely but **never pass `screenName`** — these are not screen-bound
 - Metrics: wrap the async operation between `startOperation()` and `complete()`/`fail()`
 
 **What NOT to instrument:**
@@ -296,3 +393,10 @@ Every event automatically includes:
 - `_connection` — network type (wifi, cellular, ethernet, offline) via `NWPathMonitor`
 - `experiments` — current A/B experiment assignments
 - `environment` — specific runtime (ios, ipados, macos)
+
+**Auto-emitted lifecycle events** (no manual calls needed):
+- `sdk:session_started` — on `configure()`, includes `_launch_ms` (time from process start to configure)
+- `sdk:app_foregrounded` — when app enters foreground
+- `sdk:app_backgrounded` — when app enters background
+- `sdk:screen_appeared` (info) / `sdk:screen_disappeared` (debug) — when using `.owlScreen()` modifier (disappear includes `_duration_ms`)
+- `sdk:network_request` (info/warn/error) — URLSession HTTP requests with method, URL, status, duration (enabled by default, disable with `networkTrackingEnabled: false`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmetry/cli",
-  "version": "0.1.3",
+  "version": "0.1.7",
   "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",