Summary
Produce a weekly acquisition/activation funnel rollup from data that already exists: npm downloads, local telemetry events, and .agents/observability/executions.jsonl. Today nobody can answer "of N downloads this week, how many ran an agent twice?" — the single number that tells us whether the OSS motion is a funnel or a hobby.
Spec
Command: squads telemetry rollup
Flags:
--weeks <n> (default 4) — trailing calendar weeks--out <path> (default .agents/observability/funnel-<YYYY>-W<ww>.md; also print table to stdout)--offline — skip the npm fetch, local data only
Funnel stages (weekly buckets):
- Downloads — npm registry downloads API for the package (public endpoint, e.g.
https://api.npmjs.org/downloads/point/last-week/<pkg>; use the range API for multi-week)
- Installs with telemetry — distinct install IDs seen in first-party telemetry events (opt-in, disclosed — count only what the disclosure covers)
init ran — telemetry command events- First
run — command events
- Second
run (returning activation) — same install ID, distinct week or ≥24h later
login attempts — command events including failed/degraded ones
Local-only mode (when telemetry pipe has no data — e.g. analyzing a single project's own usage) buckets stages 3–6 from executions.jsonl + telemetry events on this machine and says so in the header.
Output: markdown table, one row per week, one column per stage, with week-over-week deltas. Header states data sources and coverage honestly (e.g. "telemetry covers opt-in installs only — true funnel is wider at the top"). Missing source → column renders —, never interpolated.
Rules:
- No new dependencies (native fetch)
- No PII: counts only, no install IDs in the output
- No network in
--offline mode; tests must use --offline + fixtures
Acceptance criteria
Out of scope
- Dashboards/charts, GA4 integration, hosted collection
One branch, one PR to develop, Closes #<this-issue>.
Summary
Produce a weekly acquisition/activation funnel rollup from data that already exists: npm downloads, local telemetry events, and
.agents/observability/executions.jsonl. Today nobody can answer "of N downloads this week, how many ran an agent twice?" — the single number that tells us whether the OSS motion is a funnel or a hobby.Spec
Command:
squads telemetry rollupFlags:
--weeks <n>(default4) — trailing calendar weeks--out <path>(default.agents/observability/funnel-<YYYY>-W<ww>.md; also print table to stdout)--offline— skip the npm fetch, local data onlyFunnel stages (weekly buckets):
https://api.npmjs.org/downloads/point/last-week/<pkg>; use the range API for multi-week)initran — telemetry command eventsrun— command eventsrun(returning activation) — same install ID, distinct week or ≥24h laterloginattempts — command events including failed/degraded onesLocal-only mode (when telemetry pipe has no data — e.g. analyzing a single project's own usage) buckets stages 3–6 from
executions.jsonl+ telemetry events on this machine and says so in the header.Output: markdown table, one row per week, one column per stage, with week-over-week deltas. Header states data sources and coverage honestly (e.g. "telemetry covers opt-in installs only — true funnel is wider at the top"). Missing source → column renders
—, never interpolated.Rules:
--offlinemode; tests must use--offline+ fixturesAcceptance criteria
--offlineon fixtures produces the correct weekly buckets and deltas—, not zerosdocs/commands.mdentryOut of scope
One branch, one PR to
develop,Closes #<this-issue>.