Write a scripts-v2 script

Background on Autumn's data model. For general Autumn domain concepts — FullCusProduct shape, the three item categories, prepaid pricing, entity-level vs entity-scoped — see the skills under ai/config/skills/autumn/. Read the relevant one (e.g. customer-products) BEFORE writing any script that mutates customer products, prices, or entitlements.

Stripe resource creation. For helpers that create Stripe prices/products/meters tied to Autumn prices (idempotent, V1+V2 prepaid pairing, volume-tier shape), see ai/config/skills/autumn/stripe-resources. Read it BEFORE writing any catalog migration that touches Stripe.

Shared utility functions. For the naming conventions (is*, <src>To<dst>, enrich*, find*, filter*By*) and folder layout of autumn/shared/utils/, see ai/config/skills/autumn/shared-utils. Check it BEFORE writing inline array.filter(...).some(...) or array.find(... === id) over Autumn objects — there is almost certainly an existing helper.

1. Read PATTERNS.md to pick the right script category
2. Create a dedicated folder for the script under runs/{org-name}/
3. Copy template.ts as the scaffold into that folder
4. Fill in config: id, org, env, dryRun: true, params
5. If the script needs non-trivial Autumn DB selection logic, use the write-autumn-query skill first
6. Implement run using s.step() for inline phases, s.run() for named step functions, s.batch() for iteration
7. For multi-file scripts, put Autumn candidate-fetching files in loaders/, define steps with step(), and compose with s.run()
8. Name the entrypoint file after what it does; do not use index.ts
9. Check SERVICES.md for available imports
10. For Google Sheets exports, read google-sheets.md

Rules

• dryRun: true by default
• All tunables in params -- no CLI args, no scattered constants
• Use ctx.logger.info() inside batch fn, never console.log()
• Named object params everywhere: fn({ db, orgId }) not fn(db, orgId)
• ctx extends AutumnContext -- pass directly to server functions
• Never name files index.ts -- name after what the function does
• Always put the script entrypoint in its own folder under runs/{org-name}/
• Follow the autumn-query-conventions rule for Autumn DB query structure
• Prefer a loaders/ folder for Autumn DB selection/query files instead of scattering them across entrypoints or ad hoc folders
• Outputs route to local data/ on laptop, S3 (scripts-us-east) on trigger.dev — never call node:fs directly. Use stores: { ... } (preferred) or await s.data.*. Sync with bun fs <script-id> pull|push (default mirrors all dirs; prompts before overwriting). Batch checkpoints live at state/checkpoint.json; dry-run checkpoints live at state/dry-run-checkpoint.json only when checkpointDryRun: true. Use params.only to force specific items to rerun even if checkpointed.
• When iterating ctx.products, filter to the latest version per product id first — the catalog carries historical versions, and most catalog migrations only want the latest. A 7-line keepLatestVersionOnly helper that picks max(version) per id is enough.
• Keep the entrypoint focused on orchestration. No inline helper functions, ad-hoc types, multi-line filter/map blocks, or detailed ctx.logger.info lines at the top level. Move them to utils/ (or steps/ if the work is a named phase). The entrypoint should read as a sequence of s.run / s.batch calls plus params / stores config — anything that takes more than 2–3 lines belongs in a sibling file. If the user asks for a log line or extra branching at the top level, put it in utils/<descriptive-name>.ts and call from the entrypoint.

One script vs split audit + delete

Default to one script with dryRun: true. The dry run lists the targets in the processed CSV + per-item logs; flipping to dryRun: false mutates the same set. No separate audit step needed.

Split into audit-*.ts + delete-*.ts only when the work is complex enough to be bug-prone — e.g. the delete set depends on human review of the CSV, selection logic is expensive and should be frozen, or the audit has multiple output buckets (for-script / not-for-script).

When splitting, put both scripts in one folder sharing config.ts, loaders/, steps/:

• Folder name describes the task (topup-blocks/, not audit-topup-balances/).
• Each script is a top-level file with a searchable name mirroring the folder (audit-topup-blocks.ts, delete-topup-blocks.ts) — never audit.ts / run.ts.
• Each script keeps a unique id (logs only, decoupled from data folder).
• Siblings share ONE auto-detected data/ folder. Downstream script reads upstream CSV via ${import.meta.dir}/data/outputs/<kebab-store-key>.csv.
• dataDir is an optional subdir under the script's own data/ — rarely needed.

step() + s.run() pattern (for multi-file scripts)

• Use step({ id, run }) to define named phases of work with typed input/output
• Use s.run(step, payload) to execute -- ctx and s are auto-injected, caller only passes business params
• Orchestrators (steps that compose other steps) take s in their run function
• Leaf steps take only ctx + business params -- no s, no data, no mutation
• Utility/helper functions stay as plain functions, no step()

Step-as-folder for multi-helper steps

When a single step grows past ~80 lines or starts pulling in 3+ named helpers, promote it from a file to a folder:

steps/
├── simple-step.ts                       # one-file step is fine when it's lean
└── complex-step/
    ├── complex-step.ts                  # the entry — exports the step({ ... })
    ├── identify-X.ts                    # selector / matcher
    ├── build-Y.ts                       # construct outputs (no DB)
    └── apply-Z-mutations.ts             # DB writes guarded by ctx.dryRun

Rules:

• The folder name MATCHES the entry file (complex-step/complex-step.ts) — searchable; never complex-step/index.ts.
• Each helper is a focused single-purpose file (identify, build, apply, validate, summarize). Avoid utils.ts / helpers.ts catch-alls.
• Other steps import only the entry (./complex-step/complex-step), never the helpers.
• This applies the same logic as the loaders/ and utils/ folders: keep the entrypoint focused on orchestration.

Batch logging with ctx.logger.set()

Inside a batch fn, use ctx.logger.set() to build up per-item context that shows what happened. This is the primary per-item output — it produces a JSON block per item showing business-level detail (customer ID, email, mutations, skip reasons, etc.).

fn: async ({ item: customerId, ctx, s }) => {
  const customer = await loadCustomer({ ctx, customerId });
  ctx.logger.set({ customerId, email: customer.email });

const result = await s.run(processCustomer, { customerId });
  ctx.logger.set({ status: result.status, updates: result.stripeUpdates });

return result;
},

Rules:

• Always ctx.logger.set() the item identifier and key business fields early
• Add mutation details (what will be added/deleted/changed) so the output shows the plan
• Inner step start/end markers are suppressed by default in batch items — ctx.logger.set() replaces them as the primary output
• Set verbose: true on the batch to see inner step markers for debugging
• ctx.logger.info() still works for freeform log lines alongside .set()

Formatting

• Always run bunx biome check --write on all new/modified script files before finishing — format only handles whitespace; check also applies import-organize, so the user's save-on-format is a no-op.

Result convention

• Functions return typed data -- never mutate caller's objects
• Fallible steps return { ok: true; ... } | { ok: false; reason: string }
• Caller checks result.ok to decide how to handle
• Batch fn returns the full typed item result
• Use onResult when the collected output row should be different from that result

```\n````

/axiom-investigate

Another lifesaving usecase is for our logging infrastructure. Internally, we have a skill called /axiom-investigate, which we use to debug customer issues by asking an agent to query and search our logs in Axiom, our logging provider. For instance, when we get a slack message, like this:

This user subscribed to a plan with the Stripe Link method, but now auto top-ups aren't working for him. Do you know why this is happening?

We can just do this:

please /axiom-investigate this thread for the org 'X':
https://autumnpricing.slack.com/archives/C0ALUV7GGGZ/p1779295652238089

It’s hard to overstate how impactful this skill has been. The time it takes to investigate issues has probably dropped 10x. Even our CEO, who had never touched Axiom before, now uses this skill daily.

This skill has been so effective (aside from the fact that we don’t sift through 100s of log lines just for a single issue), is because the results from the agent are highly accurate.

I think the reason this works so well is that we’ve spent a lot of time and effort into ensuring our logs are well structured with the right signals needed to debug issues, making querying and debugging a very repeatable process. For reference, the strategy we adopt is very similar to the concepts mentioned here.

We never did this because we knew that we’d be able to use a coding agent over it — this was well before Opus 4.5 came out and long running tasks were the norm. It was simply because logical errors are more common as a billing company. However, because our logs are so structured, our agent has all the right primitives to deliver quick and accurate investigations.

Here's the full skill:

['express']
| where ['context.customer_id'] == 'CUSTOMER_ID'
| summarize errors = countif(level == 'ERROR'), total = count() by bin(_time, 5m)
| sort by _time desc

['express']
| where ['context.customer_id'] == 'CUSTOMER_ID'
| where ['context.org_slug'] == 'ORG_SLUG'

['express']
| where ['context.customer_id'] == 'CUSTOMER_ID'
| where level in ('ERROR', 'WARN')
| sort by _time desc

['express']
| where ['context.org_slug'] == 'ORG_SLUG'
| where isnotempty(['stripe_event.type'])
| sort by _time desc

['express']
| where isnotempty(['workflow.name'])
| where level in ('ERROR', 'WARN')
| sort by _time desc

https://app.axiom.co/autumn-cxdq/query?initForm=<encoded>

node -e "const q={apl:\`['express']\n| where ...\`,queryOptions:{quickRange:'7d'}};console.log('https://app.axiom.co/autumn-cxdq/query?initForm='+encodeURIComponent(JSON.stringify(q)))"