@ai-outfitter/outfitter 1.7.1 → 1.8.1

package/docs/documentation/support-matrix.md

@@ -23,7 +23,7 @@ Tasks and bake are not in this matrix — they are the subject of a [separate up
 | Knowledge (`knowledge/`)                                                 | Supported | Partial     | Roadmap   |
 | Model selection (`models.json`)                                          | Supported | Partial     | Partial   |
 | MCP servers (`mcp.json`)                                                 | Supported | Supported   | Partial   |
-| Extensions (agent `extensions:` loadout)                                 | Supported | Roadmap     | Roadmap   |
+| Extensions (agent `extensions:` loadout)                                 | Supported | Pi only     | Pi only   |
 | Plugins (agent `plugins:` loadout)                                       | Supported | Roadmap     | Roadmap   |
 | Credentials and environment                                              | Supported | Supported   | Roadmap   |
 | DeepWork job selection                                                   | Supported | Roadmap     | Roadmap   |
@@ -38,7 +38,8 @@ Tasks and bake are not in this matrix — they are the subject of a [separate up
 
 - **Launch mode** — Outfitter launches `codex` directly. Pass-through arguments choose the native mode: no subcommand keeps the interactive CLI shape, while `-- exec ...` selects non-interactive `codex exec`.
 - **Agent identity and appended prompts** — Codex has no native identity projection yet: launches drop the composed identity/system prompt and any `--append-prompt` documents, supplied documents produce a separate warning, and `--strict` aborts before execution.
-- **Model selection (Partial)** — an agent's model maps to `-m`. Provider maps have no projection element and produce no warning. Thinking, tools, skills, subagents, extensions, plugins, and prompt templates remain unsupported and warn when selected.
+- **Model selection (Partial)** — an agent's model maps to `-m`. Provider maps have no projection element and produce no warning. Thinking, tools, skills, subagents, plugins, and prompt templates remain unsupported and warn when selected.
+- **Extensions (Pi only)** — `extensions:` names pi extension packages, so a Codex or Claude Code launch installs none of them. This is a property of the element, not a gap a user can close, so it produces no warning and does not fail under `--strict`.
 - **MCP servers (Partial)** — selected stdio fields (`command`, `args`, `env`, `cwd`) and streamable HTTP fields (`url`, `headers`) become repeated TOML-valued `-c mcp_servers.<id>.<key>=...` overrides. Server ids must contain only letters, digits, `_`, or `-`; other ids cannot be expressed by Codex `-c` key paths and are skipped with a warning. Legacy SSE and other HTTP transport types are also skipped with a warning. User and project `config.toml` servers remain active because Codex has no strict MCP isolation mode, so every launch warns that projection is additive, even when no servers are selected.
 - **Stdio environment safety** — `${ENV_NAME}` becomes an `env_vars` reference only when the stdio `env` key is also `ENV_NAME`; a reference that would rename the variable is dropped with a warning. Literal values pass through `env` and are visible in process arguments.
 - **HTTP header safety** — `${ENV_NAME}` becomes an `env_http_headers` reference, while `Authorization: Bearer ${ENV_NAME}` becomes `bearer_token_env_var`. Other header values pass through `http_headers` and are visible in process arguments. Outfitter warns for every literal stdio environment or HTTP header entry exposed in argv, so use environment references for secrets.

package/docs/documentation/telemetry.md

@@ -0,0 +1,72 @@
+# Telemetry
+
+Outfitter includes opt-outable pseudonymous product analytics to measure command adoption and reliability. A PostHog key is provisioned, so builds produced from this repository do send telemetry. The consent setting defaults to enabled and can be changed at any time.
+
+The first command that would send an event prints a one-time notice to stderr. The notice explains what is collected, what is excluded, and how to opt out.
+
+Earlier builds shipped an empty key and were fully inert: they created no client or state, sent no events, and printed no notice.
+
+## Event contract
+
+Outfitter sends exactly two event types: `cli command started` and `cli command completed`.
+
+Both events contain only these properties:
+
+| Property                  | Values                                                                                                                |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `command`                 | A registered top-level command (`run`, `setup`, `sync`, `list`, `validate`, or `dump`), or `unknown`.                 |
+| `outfitter_version`       | The installed Outfitter version.                                                                                      |
+| `node_major`              | The integer Node.js major version.                                                                                    |
+| `os_family`               | `aix`, `android`, `darwin`, `freebsd`, `linux`, `openbsd`, `sunos`, `win32`, or `unknown`.                            |
+| `arch`                    | `arm`, `arm64`, `ia32`, `loong64`, `mips`, `mipsel`, `ppc`, `ppc64`, `riscv64`, `s390`, `s390x`, `x64`, or `unknown`. |
+| `interactive`             | `true` or `false`.                                                                                                    |
+| `harness`                 | `pi`, `claude`, `codex`, or `unknown`.                                                                                |
+| `strict`                  | `true` or `false`.                                                                                                    |
+| `is_ci`                   | `true` when a CI environment is detected; otherwise `false`.                                                          |
+| `ci_name`                 | Lowercased `ci-info` vendor ID, `unknown` for unidentified CI, or `none` outside CI.                                  |
+| `$process_person_profile` | Always `false`; PostHog does not create or update a person profile.                                                   |
+
+The completed event also contains:
+
+| Property               | Values                             |
+| ---------------------- | ---------------------------------- |
+| `outcome`              | `success` or `error`.              |
+| `duration_bucket`      | `<1s`, `1-5s`, `5-30s`, or `30s+`. |
+| `exit_code_class`      | `success` or `error`.              |
+| `warning_count_bucket` | `0`, `1-5`, `5+`, or `unknown`.    |
+
+The CLI boundary does not currently have a warning counter, so `warning_count_bucket` is always `unknown`. GeoIP enrichment is disabled on the PostHog client.
+
+## Data never collected
+
+Beyond the low-cardinality `harness` and `strict` values listed above, Outfitter never sends command arguments, pass-through arguments, prompts or responses, paths, repository data, agent or profile names, settings, raw environment values, error text, stack traces, session identifiers, child-process output, hostnames, usernames, or hardware identifiers.
+
+Outside CI, the pseudonymous installation identifier is a random UUID. It is created lazily on the first capture and stored with the one-time-notice flag at `$XDG_STATE_HOME/outfitter/telemetry.json`, or `~/.local/state/outfitter/telemetry.json` when `XDG_STATE_HOME` is unset or blank. It is deliberately kept outside `~/.agents` so it cannot be committed with shared configuration.
+
+In CI, telemetry remains enabled according to the same consent rules and events are sent with `is_ci: true` and the detected `ci_name`. All runs from one CI vendor share a synthetic identifier such as `ci.github_actions`; unidentified CI uses `ci.unknown`. CI runs do not read or create `telemetry.json` and do not print the first-run notice. Set `CI=false` exactly to bypass CI detection and use the normal non-CI UUID identity and state behavior.
+
+## Where the data goes
+
+Events go to the `ai-outfitter` organization's PostHog project on PostHog Cloud US at `https://us.i.posthog.com`. No retention period is stated here because this repository does not currently configure one.
+
+## Control telemetry
+
+The source-of-truth setting is `telemetry.enabled` in `~/.agents/settings.yml`:
+
+```yaml
+telemetry:
+  enabled: false
+```
+
+Telemetry defaults to enabled when the setting is absent. Only user and user-local settings can enable it. A `false` value in user, user-local, project, or project-local settings disables it; remote or catalog settings cannot enable telemetry.
+
+If an applicable settings file cannot be parsed or validated, telemetry fails closed and a non-CI invocation removes any stored installation identifier.
+
+This settings entry is the sole persistent telemetry control. Edit the file directly to toggle it; Outfitter does not expose a telemetry command. When consent is disabled by this setting, invalid settings, or a process environment opt-out, Outfitter automatically deletes any stored pseudonymous installation identifier. If no identifier exists, cleanup remains inert and creates nothing.
+
+These environment variables disable capture for the current process:
+
+- `OUTFITTER_TELEMETRY=0`
+- `DO_NOT_TRACK=1`
+
+At exit, Outfitter gives queued analytics at most 1000 ms to shut down. Analytics failures or dropped networks never change command output, behavior, or exit status. They never delay exit beyond that budget.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-outfitter/outfitter",
-  "version": "1.7.1",
+  "version": "1.8.1",
   "description": "Profile-oriented wrapper for launching pi, Claude Code, and future agent CLIs with reproducible configuration.",
   "type": "module",
   "repository": {
@@ -36,15 +36,17 @@
     "test": "vitest --run",
     "coverage": "vitest --run --coverage",
     "check": "npm run lint:fix && npm run coverage",
-    "check-ci": "prettier --check . && npm run lint && npm run coverage"
+    "check-ci": "prettier --check . --ignore-path ../../.prettierignore && npm run lint && npm run coverage"
   },
   "dependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.3",
     "ajv": "^8.20.0",
     "chalk": "^5.6.2",
+    "ci-info": "^4.4.0",
     "commander": "^14.0.3",
     "cross-spawn": "^7.0.6",
     "liquidjs": "^10.27.0",
+    "posthog-node": "^5.49.1",
     "yaml": "^2.9.0"
   },
   "devDependencies": {

package/src/schemas/settings.schema.json

@@ -34,6 +34,17 @@
       },
       "additionalProperties": false
     },
+    "telemetry": {
+      "type": "object",
+      "description": "Controls pseudonymous Outfitter product analytics.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Enable or disable pseudonymous Outfitter product analytics. Defaults to enabled."
+        }
+      },
+      "additionalProperties": false
+    },
     "sources": {
       "type": "array",
       "items": {