Tracking Agent docs

Tracking Agent reference: config, registry and commands

This reference lists every key in .datalyze/config.yaml and _conventions.yaml, every registry entry field, and every CLI and comment command. Each key matches what the runner reads, and a key you leave out takes the default shown. _conventions.yaml is merged over the Datalyze defaults, so it only needs what differs.

.datalyze/config.yaml says how the check runs in one repo. Setup writes it; it's yours to edit in a pull request. The runner reads it from the pull request's base branch (or the default branch when the base has none), never from the pull request being checked, so a change takes effect once it merges. The same goes for everything else a pull request is judged by: _conventions.yaml and _baseline.json in the registry, .datalyze/decisions.yaml, .datalyze/conventions.md and a committed data snapshot. From the pull request itself the check takes only what waives no finding: where the typed tracker lives (typed_tracker), which side code runs on (scan.server_paths, scan.client_paths) and names built at runtime (scan.dynamic_names, each still checked against the plan).

# .datalyze/config.yaml
model:
  provider: anthropic
  max_cost_usd: 10
reviewers: [ana-k, '@acme/analytics']
allow_author_approval: false
registry: analytics/registry
install: npm ci
checks:
  - { name: typecheck, run: npx tsc --noEmit }
  - { name: lint, run: npm run lint }
platforms: [web, server]
analytics:
  tool: mixpanel
  project_id: '1234567'
  region: us
sheet:
  mode: apps_script

# analytics/registry/posts.yaml
events:
  - name: post_created
    section: Posts
    description: >-
      A post is saved by the backend after the user clicks Publish. Fires once on the server
      when the row is created, not when the editor closes.
    question: How many posts do users publish, from which entry point, and how many fail?
    track_via: server
    status: implemented
    pair: publish_clicked
    properties:
      - { name: post_id, type: string, example: 5b48c62e-5484-4225-95d5-570d4cb45992 }
      - { name: entry_point, type: string, example: editor | quick_post }
      - { name: status, type: string, example: success | failed }
      - { name: failure_reason, type: string, example: null | validation | server_error }

name, type, example, operation (set, set_once, increment, append or unset), set_via, set_when and status are required. source, question, description, pii, external, code_refs, changelog, deprecated_reason and replaced_by are optional. Super properties take name, type, example and set_when; group types in _groups.yaml take a key and a list of properties shaped like user properties without operation.

Every command except init takes --root <repo> and --registry <dir>. validate, scan, audit and diff also take --md <file> and --json <file> to save their report, and sync-sheet takes --json <file>. Exit codes: 0 clean, 1 problems found, 2 a usage or registry error.

Reviewing says who can use each one; the lists come from .datalyze/config.yaml on the pull request's base branch. Commands run from the workflow on your default branch, which GitHub uses for issue_comment events.

# .datalyze/proposals/pr-142.yaml
pr: 142
round: 1
status: in_review          # in_review, approved, implemented, verified, signed_off
method_version: 2026.10.3
items:
  - id: p1
    kind: event            # event, event_property, user_property, super_property, identity
    action: extend         # add, extend, modify, deprecate
    breaking: false
    target: post_created
    summary: The new quick-post button needs its own entry_point value.
    question: How many posts come from quick post?
    proposed: { ... }      # what the agent suggested
    final: { ... }         # what the reviewer decided; starts as a copy of proposed
    evidence:
      - code: apps/web/src/posts/QuickPost.tsx:41
    confidence: high
    note: null             # the reviewer's instruction; binding
    make_rule: false       # true adds the note to .datalyze/conventions.md
checked_unaffected:
  - publish_clicked
open_questions: []

The file carries content, never decisions: the runner ignores any decision field and takes decisions only from comment commands.