@ai-outfitter/outfitter 1.7.0 → 1.8.0

package/docs/documentation/channels.md

@@ -0,0 +1,112 @@
+# Channels
+
+A **channel** is an external source of work an agent watches — a mailbox, Signal,
+GitHub notifications, or a chat service. The
+[`ai-outfitter/channels`](https://github.com/ai-outfitter/channels) Pi extension
+owns those transports as source modules under `extensions/sources/`. A source
+opens its push connection, daemon, or polling loop and sends an **idle-gated
+wake** only when it detects matching work. Multiple sources can run at once and
+feed one notification queue.
+
+Every wake is a trusted, body-free signal. Sources that support exact-item
+actions put only an opaque locator in the wake; the agent passes that locator
+unchanged to `channel_read`, which returns the message inside explicit
+untrusted-content markers. It replies through `channel_respond`. Signal-only
+sources instead wake the agent to use that channel's existing client workflow.
+In neither case does an external message enter the session as an instruction.
+
+The extension and the response instructions have separate jobs:
+
+- `git:github.com/ai-outfitter/channels` supplies event delivery and the common
+  channel tools;
+- skills and runbooks in the Channels repository teach the agent how to handle
+  each source.
+
+Those channel skills are not published by the `community-profiles` catalog. For
+example, Channels currently carries its Slack workflow at
+[`dev/slack-responder/SKILL.md`](https://github.com/ai-outfitter/channels/blob/main/dev/slack-responder/SKILL.md)
+and its operational guides under
+[`docs/runbooks/`](https://github.com/ai-outfitter/channels/tree/main/docs/runbooks).
+
+## Add channels to an agent
+
+Add the Channels extension source to the agent's [loadout](./agents.md):
+
+```markdown
+---
+name: email-assistant
+extensions: [git:github.com/ai-outfitter/channels]
+model: your-model
+---
+```
+
+Then follow the source-specific skill or runbook in the Channels repository and
+provide that source's credentials. Do not add `mail`, `signal-responder`, or
+`slack-responder` on the assumption that they are community-catalog skill IDs.
+If you want to use the repository's development Slack skill, bring that skill
+into a catalog you control and select its resulting local ID.
+
+Because an [agent _is_ the profile](./profiles.md), a multi-channel agent still
+loads the extension only once:
+
+```markdown
+---
+name: personal-assistant
+extensions: [git:github.com/ai-outfitter/channels]
+---
+```
+
+All configured sources feed a single notification queue. Each wake names the
+sources with activity and, when available, includes opaque locators for the
+agent to pass to the common channel tools.
+
+## Select which channels run
+
+`OUTFITTER_CHANNELS` chooses the active channels; unset means **auto-detect** —
+every channel whose credentials are present starts. So composing a channel into an
+agent is really just supplying its credentials.
+
+| `OUTFITTER_CHANNELS` | Behavior                   |
+| -------------------- | -------------------------- |
+| unset                | Auto-detect by credentials |
+| `jmap,signal`        | Exactly those channels     |
+| `off` / `none`       | Disabled                   |
+
+## Credentials per channel
+
+Each source reads its configuration from environment variables. Supply them the
+Outfitter way for where the agent runs:
+
+- **Local runs** — export them in the shell before `outfitter run` (see the
+  [channels README](https://github.com/ai-outfitter/channels) for the bare-pi
+  flow).
+- **In-cluster** — project them as env from Secrets via the Kubernetes operator;
+  the operator exposes referenced Secrets without inspecting them, and the keys
+  inside are each channel's contract.
+
+| Source                   | Delivery                                                 | Variables                                                                                            |
+| ------------------------ | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `jmap` (email over JMAP) | JMAP state-change wake                                   | `XIN_BASE_URL`, `XIN_BASIC_USER`, `XIN_BASIC_PASS`                                                   |
+| `signal`                 | `signal-cli` wake                                        | `SIGNAL_NUMBER`, `SIGNAL_CLI_CONFIG`                                                                 |
+| `slack`                  | Socket Mode wake plus `channel_read` / `channel_respond` | `SLACK_APP_TOKEN`, `SLACK_BOT_TOKEN`, optional `SLACK_CHANNEL_IDS`                                   |
+| `github`                 | filtered notification wake                               | `GITHUB_NOTIFY_TOKEN` (or `GITHUB_TOKEN`), optional `GITHUB_NOTIFY_FILTERS`, `GITHUB_NOTIFY_POLL_MS` |
+
+This is only a quick orientation; the Channels README is the source of truth for
+the complete source list, credentials, prerequisites, and behavior. For a
+concrete email deployment, see its
+[Google Workspace agent-mailbox runbook](https://github.com/ai-outfitter/channels/blob/main/docs/runbooks/agent-mailbox-google-workspace.md).
+
+## Running resident
+
+A channel watcher opens push connections for the life of a session, so it needs a
+long-running agent — an interactive session, `--mode rpc`, or an always-on
+in-cluster deployment. Session switches reopen the connections; one-shot print runs
+are not suitable.
+
+## See also
+
+- [`ai-outfitter/channels`](https://github.com/ai-outfitter/channels) — the
+  extension source, channel source modules, skills, runbooks, and setup.
+- [Skills](./skills.md) — how to bring a repository-owned channel skill into a
+  catalog and select it in a loadout.
+- [Agents](./agents.md) / [Profiles](./profiles.md) — loadout and composition.

package/docs/documentation/cli.md

@@ -7,6 +7,8 @@ Global options:
 | `-V, --version` | Print the Outfitter version. |
 | `-h, --help`    | Show help for a command.     |
 
+See [Telemetry](./telemetry.md) for the pseudonymous analytics event contract and opt-out controls.
+
 ## `outfitter run [agent] [args...]`
 
 Resolve, compose, and launch an agent. `run` is the default command, so plain `outfitter` and `outfitter run` are equivalent.
@@ -15,8 +17,12 @@ Resolve, compose, and launch an agent. `run` is the default command, so plain `o
 | --------------------- | -------------------------------------------------------------------------------- |
 | `[agent]`             | Agent slug to run. Defaults to the settings `default_agent`.                     |
 | `--harness <harness>` | Harness to launch in: `pi`, `claude`, or `codex`. Defaults to `default_harness`. |
+| `--log-level <level>` | Use `info` for quiet loading or `debug` for installer output.                    |
 | `--strict`            | Fail instead of warning when the adapter cannot project part of the composition. |
 
+Set `OUTFITTER_LOG_LEVEL=debug` to enable debug startup output without passing the option. The
+`setup` command also accepts `--log-level` for its automatic profile launch.
+
 Any other arguments and unrecognized options are passed through to the launched harness:
 
 ```bash
@@ -25,6 +31,13 @@ outfitter run engineer --harness codex -- exec "review this repo"
 outfitter run persona-reviewer -- --print "summarize this repo"
 ```
 
+Because `run` is the default command, leading flags that Outfitter does not own are forwarded to the harness automatically. With a configured `default_agent`, the following forms pass flags directly to Pi:
+
+```bash
+outfitter -r            # equivalent to: outfitter run -- -r
+outfitter --resume      # equivalent to: outfitter run -- --resume
+```
+
 ## `outfitter setup [source]`
 
 Open the bundled Pi walkthrough using the original setup wording and sequence. Choose **Use the

package/docs/documentation/settings.md

@@ -40,6 +40,10 @@ remote_settings:
     ref: 9c47d1e2b8a05f36c4d7e90a12b3f8c5d6e71a04
 
 cache_directory: ./cache # optional; relative to this settings file
+
+# Pseudonymous product analytics consent; defaults to true when absent.
+telemetry:
+  enabled: false
 ```
 
 - `default_agent` / `default_harness` — which agent plain `outfitter` runs, and the harness it launches in.
@@ -48,6 +52,7 @@ cache_directory: ./cache # optional; relative to this settings file
 - `cache_directory` — the repository cache root used consistently by sync, remote settings, remote
   source resolution, and default-catalog setup. It defaults to `~/.agents/cache`; repositories live
   below its `repos/` directory.
+- `telemetry.enabled` — the primary and sole persistent control for pseudonymous product analytics. Edit it directly to enable or disable telemetry. See [Telemetry](./telemetry.md) for consent precedence, automatic identifier cleanup, the event contract, and the current inert-build status.
 
 ## Precedence
 

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,70 @@
+# Telemetry
+
+Outfitter includes opt-outable pseudonymous product analytics to measure command adoption and reliability. The shipped PostHog API key is currently empty, so no build produced from this repository sends telemetry. Provisioning a key is deferred maintainer work. The consent setting still defaults to enabled and can be changed at any time.
+
+In a future build with a provisioned key, 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. With the current empty key, telemetry is inert: it creates no client or state, sends no events, and prints 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
+
+When a maintainer provisions a PostHog key, events go to 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.0",
+  "version": "1.8.0",
   "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": {
@@ -60,7 +62,7 @@
     "vitest": "^4.1.7"
   },
   "engines": {
-    "node": ">=24.18.0 <25"
+    "node": ">=22.19.0"
   },
   "keywords": [
     "agent",

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": {