[kalmigs]

Summary

• Add a Tax section to Step 4 of the agent launch guide. A new store calculates tax from the start: every country opened under the default mode uses Fluid's tax calculation, so an agent has no tax step to do.
• For a merchant who uses their own Avalara account, list the three API calls in the order the API accepts them: save and test the credentials, switch the company to Avalara, then set each country's Avalara options and the Avalara settings. Link each call's reference page.
• Add Avalara credentials to "What to have ready", and a row to the merchant's table: the merchant gives the credentials and sets up in Avalara where they collect tax.

Part of ENG-2405

Where each claim comes from

Guide says	Source (fluid main)
A new store calculates tax with no step	Company#tax_class defaults to fluid (company.rb:236). A new country's strategy defaults to the first option, which is Fluid's own calculation (company_country.rb:133, 387-400). Signup doesn't change either. The onboarding checklist counts tax as set up (onboarding_service.rb:137)
The first environment saved is the active one	PUT /api/settings/avalara_account description in settings-v0.yaml
Avalara mode is refused until an environment is active	company.rb:1070
Switching the mode clears each country's tax strategy	Help page §Choose your tax mode; set_tax_class_action.rb:19
Commits are US and Canada only	company_country.rb:473-507; help page §Country tax settings

Checks

eval/check-guide-claims.mjs and eval/check-advertised-docs-links.mjs pass locally. eval/check-broken-links.mjs resolves every new link. It still fails on one link in setup/sales-channel-tiktok.mdx, which this PR doesn't touch, and that failure is already on main at 0115979. mint validate was not run locally. agent-launch.mdx isn't in the claims registry, so there is no registry change.

[linear-code]

ENG-2405

[otto-detective]

Otto Summary

Verdict: ✅ Approved

This is a docs-only change that adds a Tax subsection to Step 4, plus matching rows in "What to have ready" and in the merchant table. All five API reference links match operations in the specs: taxes PUT avalara_account, taxes test_connection, companies set_tax_class, countries PUT company_countries/{id}, and taxes Avalara settings. The field names (username, password, environment sandbox/production, company_code) and the claim that the first saved slot becomes active both match settings-v0.yaml. The earlier finding about mapping credential names to API fields is fixed, and I found no new issues.

Findings

No new findings.

Tip

Merge confidence: 5/5 — Docs-only change whose links and API field names match the specs in the repo.

---

Confidence trend (oldest → newest): 5/5 → 5/5 → 5/5 → 5/5

Review history (4 runs)

Reviewed	Commit	Verdict	Score	New findings
2026-10-21 05:08 UTC (latest)	99bf5df	Approved	5/5	0
2026-10-21 04:57 UTC	91755c9	Approved	5/5	0
2026-10-20 15:55 UTC	fe42485	Approved	5/5	0
2026-10-20 14:34 UTC	98cfb4b	Approved	5/5	1

[otto-detective]

Otto reviewed 98cfb4b. 1 new inline finding.

Tip

Merge confidence: 5/5 — Docs-only change: the links resolve to existing spec operations and the claims match the specs and the help page.

The full summary and review history are in Otto's pinned summary comment, updated on every review.

[otto-detective]

Map credential names to API fields

This uses the admin UI's labels (account ID, license key), but the PUT /api/settings/avalara_account body calls these fields username and password, next to company_code. Since this guide is for agents calling the API, a short parenthetical such as "(sent as username and password)" here or in step 1 of the Tax section would save a lookup.

Prompt To Fix With AI

This is a comment left during a code review.
Path: api/agent-launch.mdx
Line: 54
Severity: P3

Comment:
**Map credential names to API fields**

This uses the admin UI's labels (account ID, license key), but the `PUT /api/settings/avalara_account` body calls these fields `username` and `password`, next to `company_code`. Since this guide is for agents calling the API, a short parenthetical such as "(sent as `username` and `password`)" here or in step 1 of the Tax section would save a lookup.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this feedback doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[otto-detective]

Fixed. Step 1 of the Tax section now maps account ID → username and license key → password.

[kalmigs]

The red validate check comes from main, not this PR. Main's API reference sync (0115979) renamed a TikTok operation. That broke a link in setup/sales-channel-tiktok.mdx and the admin-v2025-06 page map in check-hosted-docs.test.mjs. #175 fixes both. I'll rebase this PR once it merges.

[otto-detective]

Otto reviewed fe42485. No new inline findings.

Tip

Merge confidence: 5/5 — Docs-only change: the claims have sources, the links resolve, and the earlier finding is fixed.

The full summary and review history are in Otto's pinned summary comment, updated on every review.

[cwcarlson10]

Approving. I checked each claim in the new Tax section against the app, and they hold: a new store defaults to Fluid's tax calculation, the first Avalara environment saved becomes the active one, the Avalara mode is refused until an environment is active, switching the mode clears each country's tax strategy, and commits are US and Canada only. The call order is right too.

One suggestion on step 2. Its reason is a little off. The mode switch clears the tax strategy, but it doesn't touch the fields step 3 sets. The real reason to switch first is that Fluid refuses to turn on commits until the country's tax mode is Avalara. Saying that tells an agent why a step 3 call fails if it runs out of order. I also left a small nit about the company code. Neither one blocks the merge.

The red validate check is the TikTok link and the admin page map from main. #175 fixes both, as you said.

[cwcarlson10]

The mode switch clears each country's tax strategy, but it leaves the commit and company code settings alone, so that isn't why step 3 has to wait. The reason is that Fluid refuses to turn on Commit transactions to Avalara until the country's tax mode is Avalara. Suggested wording: "Switch the company to Avalara with Set the tax class for a company. Fluid turns on commits only for a country that uses Avalara, so do this before step 3. The switch also clears each country's tax strategy."

[kalmigs]

Done in 91755c9, with your wording.

[cwcarlson10]

Nit: this reads as if all three values are required. The API saves the slot without a company code, and the help page says the code is needed only to commit transactions. Maybe: "the account ID and license key, plus the company code if they commit transactions to Avalara."

[kalmigs]

Done in 91755c9. Step 1 said the same thing, so I fixed it there too.

[otto-detective]

Otto reviewed 91755c9. No new inline findings.

Tip

Merge confidence: 5/5 — The change is docs-only, its claims are sourced, the links are checked and the earlier finding is fixed.

The full summary and review history are in Otto's pinned summary comment, updated on every review.

[otto-detective]

Otto reviewed 99bf5df. No new inline findings.

Tip

Merge confidence: 5/5 — Docs-only change whose links and API field names match the specs in the repo.

The full summary and review history are in Otto's pinned summary comment, updated on every review.