158909 :: docs: AutoPay public documentation

[ankitottu]

Redmine epic #158909 — closes the docs half of the AutoPay launch.

Merges the epic branch into dev, which deploys to docs.ottu.dev for review. Nothing reaches docs.ottu.com until it has been signed off there — that is #158915.

What ships

#158910	Developer section at /developers/payments/autopay/ + AutoPayFlowDiagram + glossary terms + payments-index entry
#158912	Business section at /business/autopay/, one long page with a Pattern-A anchor sub-menu
#158913 (partial)	20 customer-portal and notification screenshots from Menna
—	Design spec + execution plan under docs/superpowers/

Both child PRs (#167, #168) already merged here. sidebars.ts was edited once, in the scaffold commit, so the two lanes never touched the same file.

The distinction the whole thing hangs on

With auto_debit the merchant owns the billing schedule, retries and dunning. With auto_pay, AutoPay owns them.

recurring-payments.mdx is the closest existing page and readers will land on the wrong one, so both pages now cross-link with an explicit "use this when".

Facts documented that appear in no ticket

Found by reading autopay/subscriptions/ and by a live betabulk call:

• The autopay request block is write-only — not echoed in the 201. extra.autopay.subscription_id is the merchant's only handle. Verified live: sub_hA1YYmZz1xk8speCiPbOquIP.
• customer_email is required. Omitting it 422s inside AutoPay and surfaces as 400 {"autopay":["AutoPayClient rejected request (422)"]} — reads like an agreement-shape error and is not.
• page-link does not rotate the token; regenerate-page-token revokes. A merchant reaching for regenerate when they meant re-send silently breaks the customer's working link, with no notification to that customer.
• retry_window_days is dead — dropped in migrations/0028_drop_retry_window_days.py. ⚠️#158911's field table still lists it as live with a 1–30 range. That table is also the spec for the enrichment YAML, so it needs correcting there too.
• list returns a slim summary, not full subscription objects.
• The customer page token is signed, not encrypted — the payload is readable base64. Treat the link like a password.

Known gaps, deliberate

Gap	Why
## API Reference is a placeholder	core_backend PR 121 unmerged — static/Ottu_API.yaml has zero autopay occurrences, so <ApiDocEmbed> cannot resolve. Endpoints documented as prose + cURL under ## Guide instead.
Endpoint base path unconfirmed	Samples use AutoPay's own root-mounted paths. Merchants reach these through a Connect proxy whose public path is in PR 121. @yamen — needs your answer.
JWT acquisition undocumented	Five of six endpoints need a Keycloak JWT; the auth guide only covers Api-Key. Flagged in a :::warning on the page rather than papered over.
No merchant dashboard content	It does not exist — REST-API-only this phase, confirmed by @dacian 2026-08-13.
No add-card screenshot	Not captured yet; behaviour written as prose, no image referenced.
No video	Remotion is #158914, decoupled.

Verification

• npm run typecheck ✅ · npm run build ✅
• Both pages adversarially verified by subagents against their tickets' own acceptance criteria: developer 14 PASS / 1 BLOCKED, business 13 PASS
• Checked by hand in Chrome against the local production build — onBrokenLinks is "warn", so a green build proves nothing about navigation:
  • business sidebar anchors 10/10 resolve, developer 5/5, in-page links 21/21
  • every referenced image returns HTTP 200
  • flow diagram renders correctly in light and dark mode
• Every behavioural claim traced to autopay/subscriptions/enums.py, models.py, schemas.py or tasks/_tenant_processors.py

⚠️ One thing to look at before approving

portal-01-summary-active.png is the hero image on the business page and it is a mockup that contradicts the real product. Checked against a live betabulk portal: it shows an invoice Download column (AutoPay stores no invoices), a Pay Now button on an active subscription (Pay Now only exists when past due), two cards both masked *** 1234, and a next-payment date a year adrift from its own history.

The prose no longer describes any of it, but a reader still sees it. Recutting that one image — or a straight recapture from betabulk — is the highest-value screenshot task left. @junaid@Menna

Sign-off needed (#158915)

• @yamen — backend and API accuracy, PR 121, proxy base path
• @ankit — AutoPay behaviour and business accuracy
• @junaid / @Menna — visual review

Do not merge until reviewed on this branch.

[jab3z]

@claude review

[claude]

Claude finished @jab3z's task in 3m 14s —— View job

---

Review complete

• Gather context (PR body, changed files list)
• Read diff (git diff origin/dev...HEAD)
• Review developer AutoPay page + flow diagram
• Review business AutoPay page
• Review sidebars.ts, glossary, cross-links
• Check CLAUDE.md compliance (API base URL constant, merchant_id, cross-linking, etc.)
• Post final review

Note: node_modules isn't installed in this sandbox and installing it wasn't in scope, so I couldn't independently re-run npm run build/npm run typecheck — this review is a manual read of the diff against origin/dev and the repo's CLAUDE.md conventions.

Overall this is a strong, well-verified page pair — the sidebar anchor hygiene (sidebars.ts) all checks out against actual heading IDs on both pages, the <AutoPayFlowDiagram> follows the svg-diagram skill convention correctly (monochrome + 2 accent nodes, light/dark overrides), OTTU_CONNECT_BASE_URL is used consistently instead of hardcoded URLs, and the cross-linking between AutoPay and recurring-payments.mdx is exactly the kind of disambiguation the domain needs. A few things worth a look before merging to dev:

1. "Copy-paste accurate" claim conflicts with the PR's own "base path unconfirmed" gap

docs/developers/payments/autopay/index.mdx:437-441 (API Reference section):

"Every request and response shown above is copy-paste accurate"

But the PR description itself flags "Endpoint base path unconfirmed... Merchants reach these through a Connect proxy whose public path is in PR 121 — @yamen needs your answer." The six subscription-management cURL examples (#step-by-step) hit plain ${OTTU_CONNECT_BASE_URL}/subscriptions/... with no proxy prefix, while the one endpoint you have confirmed (checkout, step 1) is prefixed /b/checkout/v1/pymt-txn/. Since the base path for steps 2–6 is explicitly still pending confirmation, the "copy-paste accurate" claim overstates what's verified — a developer could reasonably build against /subscriptions/... directly and hit 404s once the real proxy path lands. Consider either softening that line or adding the same base-path caveat that's already implicit in the PR's "known gaps" table, so it's visible to a reader on docs.ottu.dev, not just to reviewers on this PR.
Fix this →

2. New glossary terms aren't linked from either new page

src/data/glossary-terms.ts adds Billing Cycle, Dunning, and Subscription, all introduced specifically for AutoPay — but neither docs/developers/payments/autopay/index.mdx nor docs/business/autopay/index.md links to /glossary/ on first use, despite root CLAUDE.md's "no jargon without definition — first use links to the glossary" rule and the developer CLAUDE.md cross-referencing table. (This rule is loosely followed elsewhere in the repo too, so treat this as a nice-to-have rather than a blocker — but since these terms were added for this PR, it's a natural fit to wire them up here.)

3. Two shipped screenshots are never referenced, one contradicts the page copy

git diff --stat shows 20 new business screenshots, but only 18 are referenced from docs/business/autopay/index.md:

• static/img/business/autopay/portal-04-expired.png — the "Expired" step in the state <StepGuide> (docs/business/autopay/index.md:135-138) has no image/imageAlt, even though this exact screenshot exists.
• static/img/business/autopay/cards-01-delete-confirm.png — unreferenced anywhere. This one is worth double-checking specifically: the page states "Saved cards are never deleted... there is no removal step to walk them through" (line 195), but a screenshot named cards-01-delete-confirm strongly implies a delete-confirmation dialog exists in the product. Given the PR already flagged portal-01-summary-active.png as a stale mockup that contradicts the real product, this looks like it could be the same class of issue — either the copy is right and this is a leftover asset that should be dropped, or card deletion does exist and the copy needs correcting. Worth a quick check with @Menna/@junaid alongside the portal-01 fix.

Not re-litigated

The factual claims (write-only autopay block, customer_email 422 behavior, page-link vs regenerate-page-token, dead retry_window_days, slim list summary, signed-not-encrypted token) all match what's described in the PR body as independently verified against autopay/subscriptions/ source and a live betabulk call — I didn't have backend access to re-verify these, so I'm relying on the PR author's stated verification method there.
· branch epic/158909

[ankitottu]

@claude re-review

[claude]

Claude finished @ankitottu's task in 1m 38s —— View job

---

Re-review complete

• Gather context (PR body, prior review, changed files)
• Check what changed since the last review (commit 34e4484)
• Verify the three prior findings were actually resolved
• Fresh pass over the full diff for anything new
• Post final review

Note: node_modules still isn't installed in this sandbox, so I couldn't independently re-run npm run build/npm run typecheck — this is a manual read of git diff origin/dev...HEAD plus the four fix commits added since the first review (b5475bf, 79835e2, 93c1567, 34e4484).

All three points from the first review are resolved cleanly in 34e4484:

1. "Copy-paste accurate" overclaim — fixed. docs/developers/payments/autopay/index.mdx:62-65 now has a dedicated :::warning The path in front of /subscriptions/ isn't final block naming exactly what's unconfirmed (the Connect proxy prefix for Steps 2–6) while explicitly stating headers/bodies/responses/behaviour are accurate, and that Step 1's /b/checkout/v1/pymt-txn/ is stable. The old blanket "copy-paste accurate" line under ## API Reference (line ~444) was replaced with a pointer to that scoped caveat instead of a second overclaim. This is exactly the right fix — it's visible to a reader on docs.ottu.dev now, not just to PR reviewers.

2. Glossary terms unlinked — fixed. Billing Cycle, Dunning, and Subscription are each now linked once per page via /glossary/#term-<id>. Verified the anchor mechanism actually resolves: src/components/GlossarySearch/index.tsx:7,30-31 builds/reads the same term-${id} hash format server-side, and the ids added in src/data/glossary-terms.ts (billing-cycle, dunning, subscription) match what's linked. The commit message's note that Docusaurus's broken-link checker will still flag these as a false positive (same pattern as the existing payment-states/transaction-states pages) checks out.

3. Unreferenced/contradictory screenshots — fixed correctly, not just papered over. Both cards-01-delete-confirm.png and portal-04-expired.png are deleted from the tree (not just dereferenced), so they can't get silently wired back in later. Confirmed no remaining references to either filename anywhere in the repo, and confirmed all 19 remaining business screenshots (20 shipped − 2 dropped − wait, 18 referenced + the dropped 2 = 20 ✓) are each referenced from docs/business/autopay/index.md. The "Expired" step in the state <StepGuide> (docs/business/autopay/index.md:135-138) now correctly has no image/imageAlt at all, matching its terminal-state description instead of showing a fabricated Reactivate button.

One thing worth noting rather than re-flagging: portal-01-summary-active.png (the hero mockup the PR body itself calls out as contradicting the real product) is still in place — that's expected, since the PR description already tracks it as the open "highest-value screenshot task left" pending recapture from betabulk, not something silently missed.

Also scanned the intervening accuracy commit (93c1567, notification keys / list-summary shape / cycle statuses) — it's a good-faith correctness pass against autopay/subscriptions/{enums,schemas}.py unrelated to the review findings, nothing to flag there.

Nothing new surfaced in this pass. The two page diffs are clean additions with no leftover inconsistencies from the fix-up commits.
· branch

[ankitottu]

Redmine epic #158909 — closes the docs half of the AutoPay launch.

Merges the epic branch into dev, which deploys to docs.ottu.dev for review. Nothing reaches docs.ottu.com until it has been signed off there — that is #158915.

What ships

#158910	Developer section at /developers/payments/autopay/ + AutoPayFlowDiagram + glossary terms + payments-index entry
#158912	Business section at /business/autopay/, one long page with a Pattern-A anchor sub-menu
#158913 (partial)	20 customer-portal and notification screenshots from Menna
—	Design spec + execution plan under docs/superpowers/

Both child PRs (#167, #168) already merged here. sidebars.ts was edited once, in the scaffold commit, so the two lanes never touched the same file.

The distinction the whole thing hangs on

With auto_debit the merchant owns the billing schedule, retries and dunning. With auto_pay, AutoPay owns them.

recurring-payments.mdx is the closest existing page and readers will land on the wrong one, so both pages now cross-link with an explicit "use this when".

Facts documented that appear in no ticket

Found by reading autopay/subscriptions/ and by a live betabulk call:

• The autopay request block is write-only — not echoed in the 201. extra.autopay.subscription_id is the merchant's only handle. Verified live: sub_hA1YYmZz1xk8speCiPbOquIP.
• customer_email is required. Omitting it 422s inside AutoPay and surfaces as 400 {"autopay":["AutoPayClient rejected request (422)"]} — reads like an agreement-shape error and is not.
• page-link does not rotate the token; regenerate-page-token revokes. A merchant reaching for regenerate when they meant re-send silently breaks the customer's working link, with no notification to that customer.
• retry_window_days is dead — dropped in migrations/0028_drop_retry_window_days.py. ⚠️#158911's field table still lists it as live with a 1–30 range. That table is also the spec for the enrichment YAML, so it needs correcting there too.
• list returns a slim summary, not full subscription objects.
• The customer page token is signed, not encrypted — the payload is readable base64. Treat the link like a password.

Known gaps, deliberate

Gap	Why
## API Reference is a placeholder	core_backend PR 121 unmerged — static/Ottu_API.yaml has zero autopay occurrences, so <ApiDocEmbed> cannot resolve. Endpoints documented as prose + cURL under ## Guide instead.
Endpoint base path unconfirmed	Samples use AutoPay's own root-mounted paths. Merchants reach these through a Connect proxy whose public path is in PR 121. @yamen — needs your answer.
JWT acquisition undocumented	Five of six endpoints need a Keycloak JWT; the auth guide only covers Api-Key. Flagged in a :::warning on the page rather than papered over.
No merchant dashboard content	It does not exist — REST-API-only this phase, confirmed by @dacian 2026-08-13.
No add-card screenshot	Not captured yet; behaviour written as prose, no image referenced.
No video	Remotion is #158914, decoupled.

Verification

• npm run typecheck ✅ · npm run build ✅
• Both pages adversarially verified by subagents against their tickets' own acceptance criteria: developer 14 PASS / 1 BLOCKED, business 13 PASS
• Checked by hand in Chrome against the local production build — onBrokenLinks is "warn", so a green build proves nothing about navigation:
  • business sidebar anchors 10/10 resolve, developer 5/5, in-page links 21/21
  • every referenced image returns HTTP 200
  • flow diagram renders correctly in light and dark mode
• Every behavioural claim traced to autopay/subscriptions/enums.py, models.py, schemas.py or tasks/_tenant_processors.py

⚠️ One thing to look at before approving

portal-01-summary-active.png is the hero image on the business page and it is a mockup that contradicts the real product. Checked against a live betabulk portal: it shows an invoice Download column (AutoPay stores no invoices), a Pay Now button on an active subscription (Pay Now only exists when past due), two cards both masked *** 1234, and a next-payment date a year adrift from its own history.

The prose no longer describes any of it, but a reader still sees it. Recutting that one image — or a straight recapture from betabulk — is the highest-value screenshot task left. @junaid@Menna

Sign-off needed (#158915)

• @yamen — backend and API accuracy, PR 121, proxy base path
• @ankit — AutoPay behaviour and business accuracy
• @junaid / @Menna — visual review

Do not merge until reviewed on this branch.

[jab3z]

@claude review

[claude]

Claude finished @jab3z's task in 3m 14s —— View job

---

Review complete

• Gather context (PR body, changed files list)
• Read diff (git diff origin/dev...HEAD)
• Review developer AutoPay page + flow diagram
• Review business AutoPay page
• Review sidebars.ts, glossary, cross-links
• Check CLAUDE.md compliance (API base URL constant, merchant_id, cross-linking, etc.)
• Post final review

Note: node_modules isn't installed in this sandbox and installing it wasn't in scope, so I couldn't independently re-run npm run build/npm run typecheck — this review is a manual read of the diff against origin/dev and the repo's CLAUDE.md conventions.

Overall this is a strong, well-verified page pair — the sidebar anchor hygiene (sidebars.ts) all checks out against actual heading IDs on both pages, the <AutoPayFlowDiagram> follows the svg-diagram skill convention correctly (monochrome + 2 accent nodes, light/dark overrides), OTTU_CONNECT_BASE_URL is used consistently instead of hardcoded URLs, and the cross-linking between AutoPay and recurring-payments.mdx is exactly the kind of disambiguation the domain needs. A few things worth a look before merging to dev:

1. "Copy-paste accurate" claim conflicts with the PR's own "base path unconfirmed" gap

docs/developers/payments/autopay/index.mdx:437-441 (API Reference section):

"Every request and response shown above is copy-paste accurate"

But the PR description itself flags "Endpoint base path unconfirmed... Merchants reach these through a Connect proxy whose public path is in PR 121 — @yamen needs your answer." The six subscription-management cURL examples (#step-by-step) hit plain ${OTTU_CONNECT_BASE_URL}/subscriptions/... with no proxy prefix, while the one endpoint you have confirmed (checkout, step 1) is prefixed /b/checkout/v1/pymt-txn/. Since the base path for steps 2–6 is explicitly still pending confirmation, the "copy-paste accurate" claim overstates what's verified — a developer could reasonably build against /subscriptions/... directly and hit 404s once the real proxy path lands. Consider either softening that line or adding the same base-path caveat that's already implicit in the PR's "known gaps" table, so it's visible to a reader on docs.ottu.dev, not just to reviewers on this PR.
Fix this →

2. New glossary terms aren't linked from either new page

src/data/glossary-terms.ts adds Billing Cycle, Dunning, and Subscription, all introduced specifically for AutoPay — but neither docs/developers/payments/autopay/index.mdx nor docs/business/autopay/index.md links to /glossary/ on first use, despite root CLAUDE.md's "no jargon without definition — first use links to the glossary" rule and the developer CLAUDE.md cross-referencing table. (This rule is loosely followed elsewhere in the repo too, so treat this as a nice-to-have rather than a blocker — but since these terms were added for this PR, it's a natural fit to wire them up here.)

3. Two shipped screenshots are never referenced, one contradicts the page copy

git diff --stat shows 20 new business screenshots, but only 18 are referenced from docs/business/autopay/index.md:

• static/img/business/autopay/portal-04-expired.png — the "Expired" step in the state <StepGuide> (docs/business/autopay/index.md:135-138) has no image/imageAlt, even though this exact screenshot exists.
• static/img/business/autopay/cards-01-delete-confirm.png — unreferenced anywhere. This one is worth double-checking specifically: the page states "Saved cards are never deleted... there is no removal step to walk them through" (line 195), but a screenshot named cards-01-delete-confirm strongly implies a delete-confirmation dialog exists in the product. Given the PR already flagged portal-01-summary-active.png as a stale mockup that contradicts the real product, this looks like it could be the same class of issue — either the copy is right and this is a leftover asset that should be dropped, or card deletion does exist and the copy needs correcting. Worth a quick check with @Menna/@junaid alongside the portal-01 fix.

Not re-litigated

The factual claims (write-only autopay block, customer_email 422 behavior, page-link vs regenerate-page-token, dead retry_window_days, slim list summary, signed-not-encrypted token) all match what's described in the PR body as independently verified against autopay/subscriptions/ source and a live betabulk call — I didn't have backend access to re-verify these, so I'm relying on the PR author's stated verification method there.
· branch epic/158909

[ankitottu]

@claude re-review

[claude]

Claude finished @ankitottu's task in 1m 38s —— View job

---

Re-review complete

• Gather context (PR body, prior review, changed files)
• Check what changed since the last review (commit 34e4484)
• Verify the three prior findings were actually resolved
• Fresh pass over the full diff for anything new
• Post final review

Note: node_modules still isn't installed in this sandbox, so I couldn't independently re-run npm run build/npm run typecheck — this is a manual read of git diff origin/dev...HEAD plus the four fix commits added since the first review (b5475bf, 79835e2, 93c1567, 34e4484).

All three points from the first review are resolved cleanly in 34e4484:

1. "Copy-paste accurate" overclaim — fixed. docs/developers/payments/autopay/index.mdx:62-65 now has a dedicated :::warning The path in front of /subscriptions/ isn't final block naming exactly what's unconfirmed (the Connect proxy prefix for Steps 2–6) while explicitly stating headers/bodies/responses/behaviour are accurate, and that Step 1's /b/checkout/v1/pymt-txn/ is stable. The old blanket "copy-paste accurate" line under ## API Reference (line ~444) was replaced with a pointer to that scoped caveat instead of a second overclaim. This is exactly the right fix — it's visible to a reader on docs.ottu.dev now, not just to PR reviewers.

2. Glossary terms unlinked — fixed. Billing Cycle, Dunning, and Subscription are each now linked once per page via /glossary/#term-<id>. Verified the anchor mechanism actually resolves: src/components/GlossarySearch/index.tsx:7,30-31 builds/reads the same term-${id} hash format server-side, and the ids added in src/data/glossary-terms.ts (billing-cycle, dunning, subscription) match what's linked. The commit message's note that Docusaurus's broken-link checker will still flag these as a false positive (same pattern as the existing payment-states/transaction-states pages) checks out.

3. Unreferenced/contradictory screenshots — fixed correctly, not just papered over. Both cards-01-delete-confirm.png and portal-04-expired.png are deleted from the tree (not just dereferenced), so they can't get silently wired back in later. Confirmed no remaining references to either filename anywhere in the repo, and confirmed all 19 remaining business screenshots (20 shipped − 2 dropped − wait, 18 referenced + the dropped 2 = 20 ✓) are each referenced from docs/business/autopay/index.md. The "Expired" step in the state <StepGuide> (docs/business/autopay/index.md:135-138) now correctly has no image/imageAlt at all, matching its terminal-state description instead of showing a fabricated Reactivate button.

One thing worth noting rather than re-flagging: portal-01-summary-active.png (the hero mockup the PR body itself calls out as contradicting the real product) is still in place — that's expected, since the PR description already tracks it as the open "highest-value screenshot task left" pending recapture from betabulk, not something silently missed.

Also scanned the intervening accuracy commit (93c1567, notification keys / list-summary shape / cycle statuses) — it's a good-faith correctness pass against autopay/subscriptions/{enums,schemas}.py unrelated to the review findings, nothing to flag there.

Nothing new surfaced in this pass. The two page diffs are clean additions with no leftover inconsistencies from the fix-up commits.
· branch

[ankitottu]

Redmine epic #158909 — closes the docs half of the AutoPay launch.

Merges the epic branch into dev, which deploys to docs.ottu.dev for review. Nothing reaches docs.ottu.com until it has been signed off there — that is #158915.

What ships

#158910	Developer section at /developers/payments/autopay/ + AutoPayFlowDiagram + glossary terms + payments-index entry
#158912	Business section at /business/autopay/, one long page with a Pattern-A anchor sub-menu
#158913 (partial)	20 customer-portal and notification screenshots from Menna
—	Design spec + execution plan under docs/superpowers/

Both child PRs (#167, #168) already merged here. sidebars.ts was edited once, in the scaffold commit, so the two lanes never touched the same file.

The distinction the whole thing hangs on

With auto_debit the merchant owns the billing schedule, retries and dunning. With auto_pay, AutoPay owns them.

recurring-payments.mdx is the closest existing page and readers will land on the wrong one, so both pages now cross-link with an explicit "use this when".

Facts documented that appear in no ticket

Found by reading autopay/subscriptions/ and by a live betabulk call:

• The autopay request block is write-only — not echoed in the 201. extra.autopay.subscription_id is the merchant's only handle. Verified live: sub_hA1YYmZz1xk8speCiPbOquIP.
• customer_email is required. Omitting it 422s inside AutoPay and surfaces as 400 {"autopay":["AutoPayClient rejected request (422)"]} — reads like an agreement-shape error and is not.
• page-link does not rotate the token; regenerate-page-token revokes. A merchant reaching for regenerate when they meant re-send silently breaks the customer's working link, with no notification to that customer.
• retry_window_days is dead — dropped in migrations/0028_drop_retry_window_days.py. ⚠️#158911's field table still lists it as live with a 1–30 range. That table is also the spec for the enrichment YAML, so it needs correcting there too.
• list returns a slim summary, not full subscription objects.
• The customer page token is signed, not encrypted — the payload is readable base64. Treat the link like a password.

Known gaps, deliberate

Gap	Why
## API Reference is a placeholder	core_backend PR 121 unmerged — static/Ottu_API.yaml has zero autopay occurrences, so <ApiDocEmbed> cannot resolve. Endpoints documented as prose + cURL under ## Guide instead.
Endpoint base path unconfirmed	Samples use AutoPay's own root-mounted paths. Merchants reach these through a Connect proxy whose public path is in PR 121. @yamen — needs your answer.
JWT acquisition undocumented	Five of six endpoints need a Keycloak JWT; the auth guide only covers Api-Key. Flagged in a :::warning on the page rather than papered over.
No merchant dashboard content	It does not exist — REST-API-only this phase, confirmed by @dacian 2026-08-13.
No add-card screenshot	Not captured yet; behaviour written as prose, no image referenced.
No video	Remotion is #158914, decoupled.

Verification

• npm run typecheck ✅ · npm run build ✅
• Both pages adversarially verified by subagents against their tickets' own acceptance criteria: developer 14 PASS / 1 BLOCKED, business 13 PASS
• Checked by hand in Chrome against the local production build — onBrokenLinks is "warn", so a green build proves nothing about navigation:
  • business sidebar anchors 10/10 resolve, developer 5/5, in-page links 21/21
  • every referenced image returns HTTP 200
  • flow diagram renders correctly in light and dark mode
• Every behavioural claim traced to autopay/subscriptions/enums.py, models.py, schemas.py or tasks/_tenant_processors.py

⚠️ One thing to look at before approving

portal-01-summary-active.png is the hero image on the business page and it is a mockup that contradicts the real product. Checked against a live betabulk portal: it shows an invoice Download column (AutoPay stores no invoices), a Pay Now button on an active subscription (Pay Now only exists when past due), two cards both masked *** 1234, and a next-payment date a year adrift from its own history.

The prose no longer describes any of it, but a reader still sees it. Recutting that one image — or a straight recapture from betabulk — is the highest-value screenshot task left. @junaid@Menna

Sign-off needed (#158915)

• @yamen — backend and API accuracy, PR 121, proxy base path
• @ankit — AutoPay behaviour and business accuracy
• @junaid / @Menna — visual review

Do not merge until reviewed on this branch.

[jab3z]

@claude review

[claude]

Claude finished @jab3z's task in 3m 14s —— View job

---

Review complete

• Gather context (PR body, changed files list)
• Read diff (git diff origin/dev...HEAD)
• Review developer AutoPay page + flow diagram
• Review business AutoPay page
• Review sidebars.ts, glossary, cross-links
• Check CLAUDE.md compliance (API base URL constant, merchant_id, cross-linking, etc.)
• Post final review

Note: node_modules isn't installed in this sandbox and installing it wasn't in scope, so I couldn't independently re-run npm run build/npm run typecheck — this review is a manual read of the diff against origin/dev and the repo's CLAUDE.md conventions.

Overall this is a strong, well-verified page pair — the sidebar anchor hygiene (sidebars.ts) all checks out against actual heading IDs on both pages, the <AutoPayFlowDiagram> follows the svg-diagram skill convention correctly (monochrome + 2 accent nodes, light/dark overrides), OTTU_CONNECT_BASE_URL is used consistently instead of hardcoded URLs, and the cross-linking between AutoPay and recurring-payments.mdx is exactly the kind of disambiguation the domain needs. A few things worth a look before merging to dev:

1. "Copy-paste accurate" claim conflicts with the PR's own "base path unconfirmed" gap

docs/developers/payments/autopay/index.mdx:437-441 (API Reference section):

"Every request and response shown above is copy-paste accurate"

But the PR description itself flags "Endpoint base path unconfirmed... Merchants reach these through a Connect proxy whose public path is in PR 121 — @yamen needs your answer." The six subscription-management cURL examples (#step-by-step) hit plain ${OTTU_CONNECT_BASE_URL}/subscriptions/... with no proxy prefix, while the one endpoint you have confirmed (checkout, step 1) is prefixed /b/checkout/v1/pymt-txn/. Since the base path for steps 2–6 is explicitly still pending confirmation, the "copy-paste accurate" claim overstates what's verified — a developer could reasonably build against /subscriptions/... directly and hit 404s once the real proxy path lands. Consider either softening that line or adding the same base-path caveat that's already implicit in the PR's "known gaps" table, so it's visible to a reader on docs.ottu.dev, not just to reviewers on this PR.
Fix this →

2. New glossary terms aren't linked from either new page

src/data/glossary-terms.ts adds Billing Cycle, Dunning, and Subscription, all introduced specifically for AutoPay — but neither docs/developers/payments/autopay/index.mdx nor docs/business/autopay/index.md links to /glossary/ on first use, despite root CLAUDE.md's "no jargon without definition — first use links to the glossary" rule and the developer CLAUDE.md cross-referencing table. (This rule is loosely followed elsewhere in the repo too, so treat this as a nice-to-have rather than a blocker — but since these terms were added for this PR, it's a natural fit to wire them up here.)

3. Two shipped screenshots are never referenced, one contradicts the page copy

git diff --stat shows 20 new business screenshots, but only 18 are referenced from docs/business/autopay/index.md:

• static/img/business/autopay/portal-04-expired.png — the "Expired" step in the state <StepGuide> (docs/business/autopay/index.md:135-138) has no image/imageAlt, even though this exact screenshot exists.
• static/img/business/autopay/cards-01-delete-confirm.png — unreferenced anywhere. This one is worth double-checking specifically: the page states "Saved cards are never deleted... there is no removal step to walk them through" (line 195), but a screenshot named cards-01-delete-confirm strongly implies a delete-confirmation dialog exists in the product. Given the PR already flagged portal-01-summary-active.png as a stale mockup that contradicts the real product, this looks like it could be the same class of issue — either the copy is right and this is a leftover asset that should be dropped, or card deletion does exist and the copy needs correcting. Worth a quick check with @Menna/@junaid alongside the portal-01 fix.

Not re-litigated

The factual claims (write-only autopay block, customer_email 422 behavior, page-link vs regenerate-page-token, dead retry_window_days, slim list summary, signed-not-encrypted token) all match what's described in the PR body as independently verified against autopay/subscriptions/ source and a live betabulk call — I didn't have backend access to re-verify these, so I'm relying on the PR author's stated verification method there.
· branch epic/158909

[ankitottu]

@claude re-review

[claude]

Claude finished @ankitottu's task in 1m 38s —— View job

---

Re-review complete

• Gather context (PR body, prior review, changed files)
• Check what changed since the last review (commit 34e4484)
• Verify the three prior findings were actually resolved
• Fresh pass over the full diff for anything new
• Post final review

Note: node_modules still isn't installed in this sandbox, so I couldn't independently re-run npm run build/npm run typecheck — this is a manual read of git diff origin/dev...HEAD plus the four fix commits added since the first review (b5475bf, 79835e2, 93c1567, 34e4484).

All three points from the first review are resolved cleanly in 34e4484:

1. "Copy-paste accurate" overclaim — fixed. docs/developers/payments/autopay/index.mdx:62-65 now has a dedicated :::warning The path in front of /subscriptions/ isn't final block naming exactly what's unconfirmed (the Connect proxy prefix for Steps 2–6) while explicitly stating headers/bodies/responses/behaviour are accurate, and that Step 1's /b/checkout/v1/pymt-txn/ is stable. The old blanket "copy-paste accurate" line under ## API Reference (line ~444) was replaced with a pointer to that scoped caveat instead of a second overclaim. This is exactly the right fix — it's visible to a reader on docs.ottu.dev now, not just to PR reviewers.

2. Glossary terms unlinked — fixed. Billing Cycle, Dunning, and Subscription are each now linked once per page via /glossary/#term-<id>. Verified the anchor mechanism actually resolves: src/components/GlossarySearch/index.tsx:7,30-31 builds/reads the same term-${id} hash format server-side, and the ids added in src/data/glossary-terms.ts (billing-cycle, dunning, subscription) match what's linked. The commit message's note that Docusaurus's broken-link checker will still flag these as a false positive (same pattern as the existing payment-states/transaction-states pages) checks out.

3. Unreferenced/contradictory screenshots — fixed correctly, not just papered over. Both cards-01-delete-confirm.png and portal-04-expired.png are deleted from the tree (not just dereferenced), so they can't get silently wired back in later. Confirmed no remaining references to either filename anywhere in the repo, and confirmed all 19 remaining business screenshots (20 shipped − 2 dropped − wait, 18 referenced + the dropped 2 = 20 ✓) are each referenced from docs/business/autopay/index.md. The "Expired" step in the state <StepGuide> (docs/business/autopay/index.md:135-138) now correctly has no image/imageAlt at all, matching its terminal-state description instead of showing a fabricated Reactivate button.

One thing worth noting rather than re-flagging: portal-01-summary-active.png (the hero mockup the PR body itself calls out as contradicting the real product) is still in place — that's expected, since the PR description already tracks it as the open "highest-value screenshot task left" pending recapture from betabulk, not something silently missed.

Also scanned the intervening accuracy commit (93c1567, notification keys / list-summary shape / cycle statuses) — it's a good-faith correctness pass against autopay/subscriptions/{enums,schemas}.py unrelated to the review findings, nothing to flag there.

Nothing new surfaced in this pass. The two page diffs are clean additions with no leftover inconsistencies from the fix-up commits.
· branch

[ankitottu]

Redmine epic #158909 — closes the docs half of the AutoPay launch.

Merges the epic branch into dev, which deploys to docs.ottu.dev for review. Nothing reaches docs.ottu.com until it has been signed off there — that is #158915.

What ships

#158910	Developer section at /developers/payments/autopay/ + AutoPayFlowDiagram + glossary terms + payments-index entry
#158912	Business section at /business/autopay/, one long page with a Pattern-A anchor sub-menu
#158913 (partial)	20 customer-portal and notification screenshots from Menna
—	Design spec + execution plan under docs/superpowers/

Both child PRs (#167, #168) already merged here. sidebars.ts was edited once, in the scaffold commit, so the two lanes never touched the same file.

The distinction the whole thing hangs on

With auto_debit the merchant owns the billing schedule, retries and dunning. With auto_pay, AutoPay owns them.

recurring-payments.mdx is the closest existing page and readers will land on the wrong one, so both pages now cross-link with an explicit "use this when".

Facts documented that appear in no ticket

Found by reading autopay/subscriptions/ and by a live betabulk call:

• The autopay request block is write-only — not echoed in the 201. extra.autopay.subscription_id is the merchant's only handle. Verified live: sub_hA1YYmZz1xk8speCiPbOquIP.
• customer_email is required. Omitting it 422s inside AutoPay and surfaces as 400 {"autopay":["AutoPayClient rejected request (422)"]} — reads like an agreement-shape error and is not.
• page-link does not rotate the token; regenerate-page-token revokes. A merchant reaching for regenerate when they meant re-send silently breaks the customer's working link, with no notification to that customer.
• retry_window_days is dead — dropped in migrations/0028_drop_retry_window_days.py. ⚠️#158911's field table still lists it as live with a 1–30 range. That table is also the spec for the enrichment YAML, so it needs correcting there too.
• list returns a slim summary, not full subscription objects.
• The customer page token is signed, not encrypted — the payload is readable base64. Treat the link like a password.

Known gaps, deliberate

Gap	Why
## API Reference is a placeholder	core_backend PR 121 unmerged — static/Ottu_API.yaml has zero autopay occurrences, so <ApiDocEmbed> cannot resolve. Endpoints documented as prose + cURL under ## Guide instead.
Endpoint base path unconfirmed	Samples use AutoPay's own root-mounted paths. Merchants reach these through a Connect proxy whose public path is in PR 121. @yamen — needs your answer.
JWT acquisition undocumented	Five of six endpoints need a Keycloak JWT; the auth guide only covers Api-Key. Flagged in a :::warning on the page rather than papered over.
No merchant dashboard content	It does not exist — REST-API-only this phase, confirmed by @dacian 2026-08-13.
No add-card screenshot	Not captured yet; behaviour written as prose, no image referenced.
No video	Remotion is #158914, decoupled.

Verification

• npm run typecheck ✅ · npm run build ✅
• Both pages adversarially verified by subagents against their tickets' own acceptance criteria: developer 14 PASS / 1 BLOCKED, business 13 PASS
• Checked by hand in Chrome against the local production build — onBrokenLinks is "warn", so a green build proves nothing about navigation:
  • business sidebar anchors 10/10 resolve, developer 5/5, in-page links 21/21
  • every referenced image returns HTTP 200
  • flow diagram renders correctly in light and dark mode
• Every behavioural claim traced to autopay/subscriptions/enums.py, models.py, schemas.py or tasks/_tenant_processors.py

⚠️ One thing to look at before approving

portal-01-summary-active.png is the hero image on the business page and it is a mockup that contradicts the real product. Checked against a live betabulk portal: it shows an invoice Download column (AutoPay stores no invoices), a Pay Now button on an active subscription (Pay Now only exists when past due), two cards both masked *** 1234, and a next-payment date a year adrift from its own history.

The prose no longer describes any of it, but a reader still sees it. Recutting that one image — or a straight recapture from betabulk — is the highest-value screenshot task left. @junaid@Menna

Sign-off needed (#158915)

• @yamen — backend and API accuracy, PR 121, proxy base path
• @ankit — AutoPay behaviour and business accuracy
• @junaid / @Menna — visual review

Do not merge until reviewed on this branch.

[jab3z]

@claude review

[claude]

Claude finished @jab3z's task in 3m 14s —— View job

---

Review complete

• Gather context (PR body, changed files list)
• Read diff (git diff origin/dev...HEAD)
• Review developer AutoPay page + flow diagram
• Review business AutoPay page
• Review sidebars.ts, glossary, cross-links
• Check CLAUDE.md compliance (API base URL constant, merchant_id, cross-linking, etc.)
• Post final review

Note: node_modules isn't installed in this sandbox and installing it wasn't in scope, so I couldn't independently re-run npm run build/npm run typecheck — this review is a manual read of the diff against origin/dev and the repo's CLAUDE.md conventions.

Overall this is a strong, well-verified page pair — the sidebar anchor hygiene (sidebars.ts) all checks out against actual heading IDs on both pages, the <AutoPayFlowDiagram> follows the svg-diagram skill convention correctly (monochrome + 2 accent nodes, light/dark overrides), OTTU_CONNECT_BASE_URL is used consistently instead of hardcoded URLs, and the cross-linking between AutoPay and recurring-payments.mdx is exactly the kind of disambiguation the domain needs. A few things worth a look before merging to dev:

1. "Copy-paste accurate" claim conflicts with the PR's own "base path unconfirmed" gap

docs/developers/payments/autopay/index.mdx:437-441 (API Reference section):

"Every request and response shown above is copy-paste accurate"

But the PR description itself flags "Endpoint base path unconfirmed... Merchants reach these through a Connect proxy whose public path is in PR 121 — @yamen needs your answer." The six subscription-management cURL examples (#step-by-step) hit plain ${OTTU_CONNECT_BASE_URL}/subscriptions/... with no proxy prefix, while the one endpoint you have confirmed (checkout, step 1) is prefixed /b/checkout/v1/pymt-txn/. Since the base path for steps 2–6 is explicitly still pending confirmation, the "copy-paste accurate" claim overstates what's verified — a developer could reasonably build against /subscriptions/... directly and hit 404s once the real proxy path lands. Consider either softening that line or adding the same base-path caveat that's already implicit in the PR's "known gaps" table, so it's visible to a reader on docs.ottu.dev, not just to reviewers on this PR.
Fix this →

2. New glossary terms aren't linked from either new page

src/data/glossary-terms.ts adds Billing Cycle, Dunning, and Subscription, all introduced specifically for AutoPay — but neither docs/developers/payments/autopay/index.mdx nor docs/business/autopay/index.md links to /glossary/ on first use, despite root CLAUDE.md's "no jargon without definition — first use links to the glossary" rule and the developer CLAUDE.md cross-referencing table. (This rule is loosely followed elsewhere in the repo too, so treat this as a nice-to-have rather than a blocker — but since these terms were added for this PR, it's a natural fit to wire them up here.)

3. Two shipped screenshots are never referenced, one contradicts the page copy

git diff --stat shows 20 new business screenshots, but only 18 are referenced from docs/business/autopay/index.md:

• static/img/business/autopay/portal-04-expired.png — the "Expired" step in the state <StepGuide> (docs/business/autopay/index.md:135-138) has no image/imageAlt, even though this exact screenshot exists.
• static/img/business/autopay/cards-01-delete-confirm.png — unreferenced anywhere. This one is worth double-checking specifically: the page states "Saved cards are never deleted... there is no removal step to walk them through" (line 195), but a screenshot named cards-01-delete-confirm strongly implies a delete-confirmation dialog exists in the product. Given the PR already flagged portal-01-summary-active.png as a stale mockup that contradicts the real product, this looks like it could be the same class of issue — either the copy is right and this is a leftover asset that should be dropped, or card deletion does exist and the copy needs correcting. Worth a quick check with @Menna/@junaid alongside the portal-01 fix.

Not re-litigated

The factual claims (write-only autopay block, customer_email 422 behavior, page-link vs regenerate-page-token, dead retry_window_days, slim list summary, signed-not-encrypted token) all match what's described in the PR body as independently verified against autopay/subscriptions/ source and a live betabulk call — I didn't have backend access to re-verify these, so I'm relying on the PR author's stated verification method there.
· branch epic/158909

[ankitottu]

@claude re-review

[claude]

Claude finished @ankitottu's task in 1m 38s —— View job

---

Re-review complete

• Gather context (PR body, prior review, changed files)
• Check what changed since the last review (commit 34e4484)
• Verify the three prior findings were actually resolved
• Fresh pass over the full diff for anything new
• Post final review

Note: node_modules still isn't installed in this sandbox, so I couldn't independently re-run npm run build/npm run typecheck — this is a manual read of git diff origin/dev...HEAD plus the four fix commits added since the first review (b5475bf, 79835e2, 93c1567, 34e4484).

All three points from the first review are resolved cleanly in 34e4484:

1. "Copy-paste accurate" overclaim — fixed. docs/developers/payments/autopay/index.mdx:62-65 now has a dedicated :::warning The path in front of /subscriptions/ isn't final block naming exactly what's unconfirmed (the Connect proxy prefix for Steps 2–6) while explicitly stating headers/bodies/responses/behaviour are accurate, and that Step 1's /b/checkout/v1/pymt-txn/ is stable. The old blanket "copy-paste accurate" line under ## API Reference (line ~444) was replaced with a pointer to that scoped caveat instead of a second overclaim. This is exactly the right fix — it's visible to a reader on docs.ottu.dev now, not just to PR reviewers.

2. Glossary terms unlinked — fixed. Billing Cycle, Dunning, and Subscription are each now linked once per page via /glossary/#term-<id>. Verified the anchor mechanism actually resolves: src/components/GlossarySearch/index.tsx:7,30-31 builds/reads the same term-${id} hash format server-side, and the ids added in src/data/glossary-terms.ts (billing-cycle, dunning, subscription) match what's linked. The commit message's note that Docusaurus's broken-link checker will still flag these as a false positive (same pattern as the existing payment-states/transaction-states pages) checks out.

3. Unreferenced/contradictory screenshots — fixed correctly, not just papered over. Both cards-01-delete-confirm.png and portal-04-expired.png are deleted from the tree (not just dereferenced), so they can't get silently wired back in later. Confirmed no remaining references to either filename anywhere in the repo, and confirmed all 19 remaining business screenshots (20 shipped − 2 dropped − wait, 18 referenced + the dropped 2 = 20 ✓) are each referenced from docs/business/autopay/index.md. The "Expired" step in the state <StepGuide> (docs/business/autopay/index.md:135-138) now correctly has no image/imageAlt at all, matching its terminal-state description instead of showing a fabricated Reactivate button.

One thing worth noting rather than re-flagging: portal-01-summary-active.png (the hero mockup the PR body itself calls out as contradicting the real product) is still in place — that's expected, since the PR description already tracks it as the open "highest-value screenshot task left" pending recapture from betabulk, not something silently missed.

Also scanned the intervening accuracy commit (93c1567, notification keys / list-summary shape / cycle statuses) — it's a good-faith correctness pass against autopay/subscriptions/{enums,schemas}.py unrelated to the review findings, nothing to flag there.

Nothing new surfaced in this pass. The two page diffs are clean additions with no leftover inconsistencies from the fix-up commits.
· branch

[ankitottu]

Redmine epic #158909 — closes the docs half of the AutoPay launch.

Merges the epic branch into dev, which deploys to docs.ottu.dev for review. Nothing reaches docs.ottu.com until it has been signed off there — that is #158915.

What ships

#158910	Developer section at /developers/payments/autopay/ + AutoPayFlowDiagram + glossary terms + payments-index entry
#158912	Business section at /business/autopay/, one long page with a Pattern-A anchor sub-menu
#158913 (partial)	20 customer-portal and notification screenshots from Menna
—	Design spec + execution plan under docs/superpowers/

Both child PRs (#167, #168) already merged here. sidebars.ts was edited once, in the scaffold commit, so the two lanes never touched the same file.

The distinction the whole thing hangs on

With auto_debit the merchant owns the billing schedule, retries and dunning. With auto_pay, AutoPay owns them.

recurring-payments.mdx is the closest existing page and readers will land on the wrong one, so both pages now cross-link with an explicit "use this when".

Facts documented that appear in no ticket

Found by reading autopay/subscriptions/ and by a live betabulk call:

• The autopay request block is write-only — not echoed in the 201. extra.autopay.subscription_id is the merchant's only handle. Verified live: sub_hA1YYmZz1xk8speCiPbOquIP.
• customer_email is required. Omitting it 422s inside AutoPay and surfaces as 400 {"autopay":["AutoPayClient rejected request (422)"]} — reads like an agreement-shape error and is not.
• page-link does not rotate the token; regenerate-page-token revokes. A merchant reaching for regenerate when they meant re-send silently breaks the customer's working link, with no notification to that customer.
• retry_window_days is dead — dropped in migrations/0028_drop_retry_window_days.py. ⚠️#158911's field table still lists it as live with a 1–30 range. That table is also the spec for the enrichment YAML, so it needs correcting there too.
• list returns a slim summary, not full subscription objects.
• The customer page token is signed, not encrypted — the payload is readable base64. Treat the link like a password.

Known gaps, deliberate

Gap	Why
## API Reference is a placeholder	core_backend PR 121 unmerged — static/Ottu_API.yaml has zero autopay occurrences, so <ApiDocEmbed> cannot resolve. Endpoints documented as prose + cURL under ## Guide instead.
Endpoint base path unconfirmed	Samples use AutoPay's own root-mounted paths. Merchants reach these through a Connect proxy whose public path is in PR 121. @yamen — needs your answer.
JWT acquisition undocumented	Five of six endpoints need a Keycloak JWT; the auth guide only covers Api-Key. Flagged in a :::warning on the page rather than papered over.
No merchant dashboard content	It does not exist — REST-API-only this phase, confirmed by @dacian 2026-08-13.
No add-card screenshot	Not captured yet; behaviour written as prose, no image referenced.
No video	Remotion is #158914, decoupled.

Verification

• npm run typecheck ✅ · npm run build ✅
• Both pages adversarially verified by subagents against their tickets' own acceptance criteria: developer 14 PASS / 1 BLOCKED, business 13 PASS
• Checked by hand in Chrome against the local production build — onBrokenLinks is "warn", so a green build proves nothing about navigation:
  • business sidebar anchors 10/10 resolve, developer 5/5, in-page links 21/21
  • every referenced image returns HTTP 200
  • flow diagram renders correctly in light and dark mode
• Every behavioural claim traced to autopay/subscriptions/enums.py, models.py, schemas.py or tasks/_tenant_processors.py

⚠️ One thing to look at before approving

portal-01-summary-active.png is the hero image on the business page and it is a mockup that contradicts the real product. Checked against a live betabulk portal: it shows an invoice Download column (AutoPay stores no invoices), a Pay Now button on an active subscription (Pay Now only exists when past due), two cards both masked *** 1234, and a next-payment date a year adrift from its own history.

The prose no longer describes any of it, but a reader still sees it. Recutting that one image — or a straight recapture from betabulk — is the highest-value screenshot task left. @junaid@Menna

Sign-off needed (#158915)

• @yamen — backend and API accuracy, PR 121, proxy base path
• @ankit — AutoPay behaviour and business accuracy
• @junaid / @Menna — visual review

Do not merge until reviewed on this branch.

[jab3z]

@claude review

[claude]

Claude finished @jab3z's task in 3m 14s —— View job

---

Review complete

• Gather context (PR body, changed files list)
• Read diff (git diff origin/dev...HEAD)
• Review developer AutoPay page + flow diagram
• Review business AutoPay page
• Review sidebars.ts, glossary, cross-links
• Check CLAUDE.md compliance (API base URL constant, merchant_id, cross-linking, etc.)
• Post final review

Note: node_modules isn't installed in this sandbox and installing it wasn't in scope, so I couldn't independently re-run npm run build/npm run typecheck — this review is a manual read of the diff against origin/dev and the repo's CLAUDE.md conventions.

Overall this is a strong, well-verified page pair — the sidebar anchor hygiene (sidebars.ts) all checks out against actual heading IDs on both pages, the <AutoPayFlowDiagram> follows the svg-diagram skill convention correctly (monochrome + 2 accent nodes, light/dark overrides), OTTU_CONNECT_BASE_URL is used consistently instead of hardcoded URLs, and the cross-linking between AutoPay and recurring-payments.mdx is exactly the kind of disambiguation the domain needs. A few things worth a look before merging to dev:

1. "Copy-paste accurate" claim conflicts with the PR's own "base path unconfirmed" gap

docs/developers/payments/autopay/index.mdx:437-441 (API Reference section):

"Every request and response shown above is copy-paste accurate"

But the PR description itself flags "Endpoint base path unconfirmed... Merchants reach these through a Connect proxy whose public path is in PR 121 — @yamen needs your answer." The six subscription-management cURL examples (#step-by-step) hit plain ${OTTU_CONNECT_BASE_URL}/subscriptions/... with no proxy prefix, while the one endpoint you have confirmed (checkout, step 1) is prefixed /b/checkout/v1/pymt-txn/. Since the base path for steps 2–6 is explicitly still pending confirmation, the "copy-paste accurate" claim overstates what's verified — a developer could reasonably build against /subscriptions/... directly and hit 404s once the real proxy path lands. Consider either softening that line or adding the same base-path caveat that's already implicit in the PR's "known gaps" table, so it's visible to a reader on docs.ottu.dev, not just to reviewers on this PR.
Fix this →

2. New glossary terms aren't linked from either new page

src/data/glossary-terms.ts adds Billing Cycle, Dunning, and Subscription, all introduced specifically for AutoPay — but neither docs/developers/payments/autopay/index.mdx nor docs/business/autopay/index.md links to /glossary/ on first use, despite root CLAUDE.md's "no jargon without definition — first use links to the glossary" rule and the developer CLAUDE.md cross-referencing table. (This rule is loosely followed elsewhere in the repo too, so treat this as a nice-to-have rather than a blocker — but since these terms were added for this PR, it's a natural fit to wire them up here.)

3. Two shipped screenshots are never referenced, one contradicts the page copy

git diff --stat shows 20 new business screenshots, but only 18 are referenced from docs/business/autopay/index.md:

• static/img/business/autopay/portal-04-expired.png — the "Expired" step in the state <StepGuide> (docs/business/autopay/index.md:135-138) has no image/imageAlt, even though this exact screenshot exists.
• static/img/business/autopay/cards-01-delete-confirm.png — unreferenced anywhere. This one is worth double-checking specifically: the page states "Saved cards are never deleted... there is no removal step to walk them through" (line 195), but a screenshot named cards-01-delete-confirm strongly implies a delete-confirmation dialog exists in the product. Given the PR already flagged portal-01-summary-active.png as a stale mockup that contradicts the real product, this looks like it could be the same class of issue — either the copy is right and this is a leftover asset that should be dropped, or card deletion does exist and the copy needs correcting. Worth a quick check with @Menna/@junaid alongside the portal-01 fix.

Not re-litigated

The factual claims (write-only autopay block, customer_email 422 behavior, page-link vs regenerate-page-token, dead retry_window_days, slim list summary, signed-not-encrypted token) all match what's described in the PR body as independently verified against autopay/subscriptions/ source and a live betabulk call — I didn't have backend access to re-verify these, so I'm relying on the PR author's stated verification method there.
· branch epic/158909

[ankitottu]

@claude re-review

[claude]

Claude finished @ankitottu's task in 1m 38s —— View job

---

Re-review complete

• Gather context (PR body, prior review, changed files)
• Check what changed since the last review (commit 34e4484)
• Verify the three prior findings were actually resolved
• Fresh pass over the full diff for anything new
• Post final review

Note: node_modules still isn't installed in this sandbox, so I couldn't independently re-run npm run build/npm run typecheck — this is a manual read of git diff origin/dev...HEAD plus the four fix commits added since the first review (b5475bf, 79835e2, 93c1567, 34e4484).

All three points from the first review are resolved cleanly in 34e4484:

1. "Copy-paste accurate" overclaim — fixed. docs/developers/payments/autopay/index.mdx:62-65 now has a dedicated :::warning The path in front of /subscriptions/ isn't final block naming exactly what's unconfirmed (the Connect proxy prefix for Steps 2–6) while explicitly stating headers/bodies/responses/behaviour are accurate, and that Step 1's /b/checkout/v1/pymt-txn/ is stable. The old blanket "copy-paste accurate" line under ## API Reference (line ~444) was replaced with a pointer to that scoped caveat instead of a second overclaim. This is exactly the right fix — it's visible to a reader on docs.ottu.dev now, not just to PR reviewers.

2. Glossary terms unlinked — fixed. Billing Cycle, Dunning, and Subscription are each now linked once per page via /glossary/#term-<id>. Verified the anchor mechanism actually resolves: src/components/GlossarySearch/index.tsx:7,30-31 builds/reads the same term-${id} hash format server-side, and the ids added in src/data/glossary-terms.ts (billing-cycle, dunning, subscription) match what's linked. The commit message's note that Docusaurus's broken-link checker will still flag these as a false positive (same pattern as the existing payment-states/transaction-states pages) checks out.

3. Unreferenced/contradictory screenshots — fixed correctly, not just papered over. Both cards-01-delete-confirm.png and portal-04-expired.png are deleted from the tree (not just dereferenced), so they can't get silently wired back in later. Confirmed no remaining references to either filename anywhere in the repo, and confirmed all 19 remaining business screenshots (20 shipped − 2 dropped − wait, 18 referenced + the dropped 2 = 20 ✓) are each referenced from docs/business/autopay/index.md. The "Expired" step in the state <StepGuide> (docs/business/autopay/index.md:135-138) now correctly has no image/imageAlt at all, matching its terminal-state description instead of showing a fabricated Reactivate button.

One thing worth noting rather than re-flagging: portal-01-summary-active.png (the hero mockup the PR body itself calls out as contradicting the real product) is still in place — that's expected, since the PR description already tracks it as the open "highest-value screenshot task left" pending recapture from betabulk, not something silently missed.

Also scanned the intervening accuracy commit (93c1567, notification keys / list-summary shape / cycle statuses) — it's a good-faith correctness pass against autopay/subscriptions/{enums,schemas}.py unrelated to the review findings, nothing to flag there.

Nothing new surfaced in this pass. The two page diffs are clean additions with no leftover inconsistencies from the fix-up commits.
· branch

[ankitottu]

Redmine epic #158909 — closes the docs half of the AutoPay launch.

Merges the epic branch into dev, which deploys to docs.ottu.dev for review. Nothing reaches docs.ottu.com until it has been signed off there — that is #158915.

What ships

#158910	Developer section at /developers/payments/autopay/ + AutoPayFlowDiagram + glossary terms + payments-index entry
#158912	Business section at /business/autopay/, one long page with a Pattern-A anchor sub-menu
#158913 (partial)	20 customer-portal and notification screenshots from Menna
—	Design spec + execution plan under docs/superpowers/

Both child PRs (#167, #168) already merged here. sidebars.ts was edited once, in the scaffold commit, so the two lanes never touched the same file.

The distinction the whole thing hangs on

With auto_debit the merchant owns the billing schedule, retries and dunning. With auto_pay, AutoPay owns them.

recurring-payments.mdx is the closest existing page and readers will land on the wrong one, so both pages now cross-link with an explicit "use this when".

Facts documented that appear in no ticket

Found by reading autopay/subscriptions/ and by a live betabulk call:

• The autopay request block is write-only — not echoed in the 201. extra.autopay.subscription_id is the merchant's only handle. Verified live: sub_hA1YYmZz1xk8speCiPbOquIP.
• customer_email is required. Omitting it 422s inside AutoPay and surfaces as 400 {"autopay":["AutoPayClient rejected request (422)"]} — reads like an agreement-shape error and is not.
• page-link does not rotate the token; regenerate-page-token revokes. A merchant reaching for regenerate when they meant re-send silently breaks the customer's working link, with no notification to that customer.
• retry_window_days is dead — dropped in migrations/0028_drop_retry_window_days.py. ⚠️#158911's field table still lists it as live with a 1–30 range. That table is also the spec for the enrichment YAML, so it needs correcting there too.
• list returns a slim summary, not full subscription objects.
• The customer page token is signed, not encrypted — the payload is readable base64. Treat the link like a password.

Known gaps, deliberate

Gap	Why
## API Reference is a placeholder	core_backend PR 121 unmerged — static/Ottu_API.yaml has zero autopay occurrences, so <ApiDocEmbed> cannot resolve. Endpoints documented as prose + cURL under ## Guide instead.
Endpoint base path unconfirmed	Samples use AutoPay's own root-mounted paths. Merchants reach these through a Connect proxy whose public path is in PR 121. @yamen — needs your answer.
JWT acquisition undocumented	Five of six endpoints need a Keycloak JWT; the auth guide only covers Api-Key. Flagged in a :::warning on the page rather than papered over.
No merchant dashboard content	It does not exist — REST-API-only this phase, confirmed by @dacian 2026-08-13.
No add-card screenshot	Not captured yet; behaviour written as prose, no image referenced.
No video	Remotion is #158914, decoupled.

Verification

• npm run typecheck ✅ · npm run build ✅
• Both pages adversarially verified by subagents against their tickets' own acceptance criteria: developer 14 PASS / 1 BLOCKED, business 13 PASS
• Checked by hand in Chrome against the local production build — onBrokenLinks is "warn", so a green build proves nothing about navigation:
  • business sidebar anchors 10/10 resolve, developer 5/5, in-page links 21/21
  • every referenced image returns HTTP 200
  • flow diagram renders correctly in light and dark mode
• Every behavioural claim traced to autopay/subscriptions/enums.py, models.py, schemas.py or tasks/_tenant_processors.py

⚠️ One thing to look at before approving

portal-01-summary-active.png is the hero image on the business page and it is a mockup that contradicts the real product. Checked against a live betabulk portal: it shows an invoice Download column (AutoPay stores no invoices), a Pay Now button on an active subscription (Pay Now only exists when past due), two cards both masked *** 1234, and a next-payment date a year adrift from its own history.

The prose no longer describes any of it, but a reader still sees it. Recutting that one image — or a straight recapture from betabulk — is the highest-value screenshot task left. @junaid@Menna

Sign-off needed (#158915)

• @yamen — backend and API accuracy, PR 121, proxy base path
• @ankit — AutoPay behaviour and business accuracy
• @junaid / @Menna — visual review

Do not merge until reviewed on this branch.

[jab3z]

@claude review

[claude]

Claude finished @jab3z's task in 3m 14s —— View job

---

Review complete

• Gather context (PR body, changed files list)
• Read diff (git diff origin/dev...HEAD)
• Review developer AutoPay page + flow diagram
• Review business AutoPay page
• Review sidebars.ts, glossary, cross-links
• Check CLAUDE.md compliance (API base URL constant, merchant_id, cross-linking, etc.)
• Post final review

Note: node_modules isn't installed in this sandbox and installing it wasn't in scope, so I couldn't independently re-run npm run build/npm run typecheck — this review is a manual read of the diff against origin/dev and the repo's CLAUDE.md conventions.

Overall this is a strong, well-verified page pair — the sidebar anchor hygiene (sidebars.ts) all checks out against actual heading IDs on both pages, the <AutoPayFlowDiagram> follows the svg-diagram skill convention correctly (monochrome + 2 accent nodes, light/dark overrides), OTTU_CONNECT_BASE_URL is used consistently instead of hardcoded URLs, and the cross-linking between AutoPay and recurring-payments.mdx is exactly the kind of disambiguation the domain needs. A few things worth a look before merging to dev:

1. "Copy-paste accurate" claim conflicts with the PR's own "base path unconfirmed" gap

docs/developers/payments/autopay/index.mdx:437-441 (API Reference section):

"Every request and response shown above is copy-paste accurate"

But the PR description itself flags "Endpoint base path unconfirmed... Merchants reach these through a Connect proxy whose public path is in PR 121 — @yamen needs your answer." The six subscription-management cURL examples (#step-by-step) hit plain ${OTTU_CONNECT_BASE_URL}/subscriptions/... with no proxy prefix, while the one endpoint you have confirmed (checkout, step 1) is prefixed /b/checkout/v1/pymt-txn/. Since the base path for steps 2–6 is explicitly still pending confirmation, the "copy-paste accurate" claim overstates what's verified — a developer could reasonably build against /subscriptions/... directly and hit 404s once the real proxy path lands. Consider either softening that line or adding the same base-path caveat that's already implicit in the PR's "known gaps" table, so it's visible to a reader on docs.ottu.dev, not just to reviewers on this PR.
Fix this →

2. New glossary terms aren't linked from either new page

src/data/glossary-terms.ts adds Billing Cycle, Dunning, and Subscription, all introduced specifically for AutoPay — but neither docs/developers/payments/autopay/index.mdx nor docs/business/autopay/index.md links to /glossary/ on first use, despite root CLAUDE.md's "no jargon without definition — first use links to the glossary" rule and the developer CLAUDE.md cross-referencing table. (This rule is loosely followed elsewhere in the repo too, so treat this as a nice-to-have rather than a blocker — but since these terms were added for this PR, it's a natural fit to wire them up here.)

3. Two shipped screenshots are never referenced, one contradicts the page copy

git diff --stat shows 20 new business screenshots, but only 18 are referenced from docs/business/autopay/index.md:

• static/img/business/autopay/portal-04-expired.png — the "Expired" step in the state <StepGuide> (docs/business/autopay/index.md:135-138) has no image/imageAlt, even though this exact screenshot exists.
• static/img/business/autopay/cards-01-delete-confirm.png — unreferenced anywhere. This one is worth double-checking specifically: the page states "Saved cards are never deleted... there is no removal step to walk them through" (line 195), but a screenshot named cards-01-delete-confirm strongly implies a delete-confirmation dialog exists in the product. Given the PR already flagged portal-01-summary-active.png as a stale mockup that contradicts the real product, this looks like it could be the same class of issue — either the copy is right and this is a leftover asset that should be dropped, or card deletion does exist and the copy needs correcting. Worth a quick check with @Menna/@junaid alongside the portal-01 fix.

Not re-litigated

The factual claims (write-only autopay block, customer_email 422 behavior, page-link vs regenerate-page-token, dead retry_window_days, slim list summary, signed-not-encrypted token) all match what's described in the PR body as independently verified against autopay/subscriptions/ source and a live betabulk call — I didn't have backend access to re-verify these, so I'm relying on the PR author's stated verification method there.
· branch epic/158909

[ankitottu]

@claude re-review

[claude]

Claude finished @ankitottu's task in 1m 38s —— View job

---

Re-review complete

• Gather context (PR body, prior review, changed files)
• Check what changed since the last review (commit 34e4484)
• Verify the three prior findings were actually resolved
• Fresh pass over the full diff for anything new
• Post final review

Note: node_modules still isn't installed in this sandbox, so I couldn't independently re-run npm run build/npm run typecheck — this is a manual read of git diff origin/dev...HEAD plus the four fix commits added since the first review (b5475bf, 79835e2, 93c1567, 34e4484).

All three points from the first review are resolved cleanly in 34e4484:

1. "Copy-paste accurate" overclaim — fixed. docs/developers/payments/autopay/index.mdx:62-65 now has a dedicated :::warning The path in front of /subscriptions/ isn't final block naming exactly what's unconfirmed (the Connect proxy prefix for Steps 2–6) while explicitly stating headers/bodies/responses/behaviour are accurate, and that Step 1's /b/checkout/v1/pymt-txn/ is stable. The old blanket "copy-paste accurate" line under ## API Reference (line ~444) was replaced with a pointer to that scoped caveat instead of a second overclaim. This is exactly the right fix — it's visible to a reader on docs.ottu.dev now, not just to PR reviewers.

2. Glossary terms unlinked — fixed. Billing Cycle, Dunning, and Subscription are each now linked once per page via /glossary/#term-<id>. Verified the anchor mechanism actually resolves: src/components/GlossarySearch/index.tsx:7,30-31 builds/reads the same term-${id} hash format server-side, and the ids added in src/data/glossary-terms.ts (billing-cycle, dunning, subscription) match what's linked. The commit message's note that Docusaurus's broken-link checker will still flag these as a false positive (same pattern as the existing payment-states/transaction-states pages) checks out.

3. Unreferenced/contradictory screenshots — fixed correctly, not just papered over. Both cards-01-delete-confirm.png and portal-04-expired.png are deleted from the tree (not just dereferenced), so they can't get silently wired back in later. Confirmed no remaining references to either filename anywhere in the repo, and confirmed all 19 remaining business screenshots (20 shipped − 2 dropped − wait, 18 referenced + the dropped 2 = 20 ✓) are each referenced from docs/business/autopay/index.md. The "Expired" step in the state <StepGuide> (docs/business/autopay/index.md:135-138) now correctly has no image/imageAlt at all, matching its terminal-state description instead of showing a fabricated Reactivate button.

One thing worth noting rather than re-flagging: portal-01-summary-active.png (the hero mockup the PR body itself calls out as contradicting the real product) is still in place — that's expected, since the PR description already tracks it as the open "highest-value screenshot task left" pending recapture from betabulk, not something silently missed.

Also scanned the intervening accuracy commit (93c1567, notification keys / list-summary shape / cycle statuses) — it's a good-faith correctness pass against autopay/subscriptions/{enums,schemas}.py unrelated to the review findings, nothing to flag there.

Nothing new surfaced in this pass. The two page diffs are clean additions with no leftover inconsistencies from the fix-up commits.
· branch

[ankitottu]

Redmine epic #158909 — closes the docs half of the AutoPay launch.

Merges the epic branch into dev, which deploys to docs.ottu.dev for review. Nothing reaches docs.ottu.com until it has been signed off there — that is #158915.

What ships

#158910	Developer section at /developers/payments/autopay/ + AutoPayFlowDiagram + glossary terms + payments-index entry
#158912	Business section at /business/autopay/, one long page with a Pattern-A anchor sub-menu
#158913 (partial)	20 customer-portal and notification screenshots from Menna
—	Design spec + execution plan under docs/superpowers/

Both child PRs (#167, #168) already merged here. sidebars.ts was edited once, in the scaffold commit, so the two lanes never touched the same file.

The distinction the whole thing hangs on

With auto_debit the merchant owns the billing schedule, retries and dunning. With auto_pay, AutoPay owns them.

recurring-payments.mdx is the closest existing page and readers will land on the wrong one, so both pages now cross-link with an explicit "use this when".

Facts documented that appear in no ticket

Found by reading autopay/subscriptions/ and by a live betabulk call:

• The autopay request block is write-only — not echoed in the 201. extra.autopay.subscription_id is the merchant's only handle. Verified live: sub_hA1YYmZz1xk8speCiPbOquIP.
• customer_email is required. Omitting it 422s inside AutoPay and surfaces as 400 {"autopay":["AutoPayClient rejected request (422)"]} — reads like an agreement-shape error and is not.
• page-link does not rotate the token; regenerate-page-token revokes. A merchant reaching for regenerate when they meant re-send silently breaks the customer's working link, with no notification to that customer.
• retry_window_days is dead — dropped in migrations/0028_drop_retry_window_days.py. ⚠️#158911's field table still lists it as live with a 1–30 range. That table is also the spec for the enrichment YAML, so it needs correcting there too.
• list returns a slim summary, not full subscription objects.
• The customer page token is signed, not encrypted — the payload is readable base64. Treat the link like a password.

Known gaps, deliberate

Gap	Why
## API Reference is a placeholder	core_backend PR 121 unmerged — static/Ottu_API.yaml has zero autopay occurrences, so <ApiDocEmbed> cannot resolve. Endpoints documented as prose + cURL under ## Guide instead.
Endpoint base path unconfirmed	Samples use AutoPay's own root-mounted paths. Merchants reach these through a Connect proxy whose public path is in PR 121. @yamen — needs your answer.
JWT acquisition undocumented	Five of six endpoints need a Keycloak JWT; the auth guide only covers Api-Key. Flagged in a :::warning on the page rather than papered over.
No merchant dashboard content	It does not exist — REST-API-only this phase, confirmed by @dacian 2026-08-13.
No add-card screenshot	Not captured yet; behaviour written as prose, no image referenced.
No video	Remotion is #158914, decoupled.

Verification

• npm run typecheck ✅ · npm run build ✅
• Both pages adversarially verified by subagents against their tickets' own acceptance criteria: developer 14 PASS / 1 BLOCKED, business 13 PASS
• Checked by hand in Chrome against the local production build — onBrokenLinks is "warn", so a green build proves nothing about navigation:
  • business sidebar anchors 10/10 resolve, developer 5/5, in-page links 21/21
  • every referenced image returns HTTP 200
  • flow diagram renders correctly in light and dark mode
• Every behavioural claim traced to autopay/subscriptions/enums.py, models.py, schemas.py or tasks/_tenant_processors.py

⚠️ One thing to look at before approving

portal-01-summary-active.png is the hero image on the business page and it is a mockup that contradicts the real product. Checked against a live betabulk portal: it shows an invoice Download column (AutoPay stores no invoices), a Pay Now button on an active subscription (Pay Now only exists when past due), two cards both masked *** 1234, and a next-payment date a year adrift from its own history.

The prose no longer describes any of it, but a reader still sees it. Recutting that one image — or a straight recapture from betabulk — is the highest-value screenshot task left. @junaid@Menna

Sign-off needed (#158915)

• @yamen — backend and API accuracy, PR 121, proxy base path
• @ankit — AutoPay behaviour and business accuracy
• @junaid / @Menna — visual review

Do not merge until reviewed on this branch.

[jab3z]

@claude review

[claude]

Claude finished @jab3z's task in 3m 14s —— View job

---

Review complete

• Gather context (PR body, changed files list)
• Read diff (git diff origin/dev...HEAD)
• Review developer AutoPay page + flow diagram
• Review business AutoPay page
• Review sidebars.ts, glossary, cross-links
• Check CLAUDE.md compliance (API base URL constant, merchant_id, cross-linking, etc.)
• Post final review

Note: node_modules isn't installed in this sandbox and installing it wasn't in scope, so I couldn't independently re-run npm run build/npm run typecheck — this review is a manual read of the diff against origin/dev and the repo's CLAUDE.md conventions.

Overall this is a strong, well-verified page pair — the sidebar anchor hygiene (sidebars.ts) all checks out against actual heading IDs on both pages, the <AutoPayFlowDiagram> follows the svg-diagram skill convention correctly (monochrome + 2 accent nodes, light/dark overrides), OTTU_CONNECT_BASE_URL is used consistently instead of hardcoded URLs, and the cross-linking between AutoPay and recurring-payments.mdx is exactly the kind of disambiguation the domain needs. A few things worth a look before merging to dev:

1. "Copy-paste accurate" claim conflicts with the PR's own "base path unconfirmed" gap

docs/developers/payments/autopay/index.mdx:437-441 (API Reference section):

"Every request and response shown above is copy-paste accurate"

But the PR description itself flags "Endpoint base path unconfirmed... Merchants reach these through a Connect proxy whose public path is in PR 121 — @yamen needs your answer." The six subscription-management cURL examples (#step-by-step) hit plain ${OTTU_CONNECT_BASE_URL}/subscriptions/... with no proxy prefix, while the one endpoint you have confirmed (checkout, step 1) is prefixed /b/checkout/v1/pymt-txn/. Since the base path for steps 2–6 is explicitly still pending confirmation, the "copy-paste accurate" claim overstates what's verified — a developer could reasonably build against /subscriptions/... directly and hit 404s once the real proxy path lands. Consider either softening that line or adding the same base-path caveat that's already implicit in the PR's "known gaps" table, so it's visible to a reader on docs.ottu.dev, not just to reviewers on this PR.
Fix this →

2. New glossary terms aren't linked from either new page

src/data/glossary-terms.ts adds Billing Cycle, Dunning, and Subscription, all introduced specifically for AutoPay — but neither docs/developers/payments/autopay/index.mdx nor docs/business/autopay/index.md links to /glossary/ on first use, despite root CLAUDE.md's "no jargon without definition — first use links to the glossary" rule and the developer CLAUDE.md cross-referencing table. (This rule is loosely followed elsewhere in the repo too, so treat this as a nice-to-have rather than a blocker — but since these terms were added for this PR, it's a natural fit to wire them up here.)

3. Two shipped screenshots are never referenced, one contradicts the page copy

git diff --stat shows 20 new business screenshots, but only 18 are referenced from docs/business/autopay/index.md:

• static/img/business/autopay/portal-04-expired.png — the "Expired" step in the state <StepGuide> (docs/business/autopay/index.md:135-138) has no image/imageAlt, even though this exact screenshot exists.
• static/img/business/autopay/cards-01-delete-confirm.png — unreferenced anywhere. This one is worth double-checking specifically: the page states "Saved cards are never deleted... there is no removal step to walk them through" (line 195), but a screenshot named cards-01-delete-confirm strongly implies a delete-confirmation dialog exists in the product. Given the PR already flagged portal-01-summary-active.png as a stale mockup that contradicts the real product, this looks like it could be the same class of issue — either the copy is right and this is a leftover asset that should be dropped, or card deletion does exist and the copy needs correcting. Worth a quick check with @Menna/@junaid alongside the portal-01 fix.

Not re-litigated

The factual claims (write-only autopay block, customer_email 422 behavior, page-link vs regenerate-page-token, dead retry_window_days, slim list summary, signed-not-encrypted token) all match what's described in the PR body as independently verified against autopay/subscriptions/ source and a live betabulk call — I didn't have backend access to re-verify these, so I'm relying on the PR author's stated verification method there.
· branch epic/158909

[ankitottu]

@claude re-review

[claude]

Claude finished @ankitottu's task in 1m 38s —— View job

---

Re-review complete

• Gather context (PR body, prior review, changed files)
• Check what changed since the last review (commit 34e4484)
• Verify the three prior findings were actually resolved
• Fresh pass over the full diff for anything new
• Post final review

Note: node_modules still isn't installed in this sandbox, so I couldn't independently re-run npm run build/npm run typecheck — this is a manual read of git diff origin/dev...HEAD plus the four fix commits added since the first review (b5475bf, 79835e2, 93c1567, 34e4484).

All three points from the first review are resolved cleanly in 34e4484:

1. "Copy-paste accurate" overclaim — fixed. docs/developers/payments/autopay/index.mdx:62-65 now has a dedicated :::warning The path in front of /subscriptions/ isn't final block naming exactly what's unconfirmed (the Connect proxy prefix for Steps 2–6) while explicitly stating headers/bodies/responses/behaviour are accurate, and that Step 1's /b/checkout/v1/pymt-txn/ is stable. The old blanket "copy-paste accurate" line under ## API Reference (line ~444) was replaced with a pointer to that scoped caveat instead of a second overclaim. This is exactly the right fix — it's visible to a reader on docs.ottu.dev now, not just to PR reviewers.

2. Glossary terms unlinked — fixed. Billing Cycle, Dunning, and Subscription are each now linked once per page via /glossary/#term-<id>. Verified the anchor mechanism actually resolves: src/components/GlossarySearch/index.tsx:7,30-31 builds/reads the same term-${id} hash format server-side, and the ids added in src/data/glossary-terms.ts (billing-cycle, dunning, subscription) match what's linked. The commit message's note that Docusaurus's broken-link checker will still flag these as a false positive (same pattern as the existing payment-states/transaction-states pages) checks out.

3. Unreferenced/contradictory screenshots — fixed correctly, not just papered over. Both cards-01-delete-confirm.png and portal-04-expired.png are deleted from the tree (not just dereferenced), so they can't get silently wired back in later. Confirmed no remaining references to either filename anywhere in the repo, and confirmed all 19 remaining business screenshots (20 shipped − 2 dropped − wait, 18 referenced + the dropped 2 = 20 ✓) are each referenced from docs/business/autopay/index.md. The "Expired" step in the state <StepGuide> (docs/business/autopay/index.md:135-138) now correctly has no image/imageAlt at all, matching its terminal-state description instead of showing a fabricated Reactivate button.

One thing worth noting rather than re-flagging: portal-01-summary-active.png (the hero mockup the PR body itself calls out as contradicting the real product) is still in place — that's expected, since the PR description already tracks it as the open "highest-value screenshot task left" pending recapture from betabulk, not something silently missed.

Also scanned the intervening accuracy commit (93c1567, notification keys / list-summary shape / cycle statuses) — it's a good-faith correctness pass against autopay/subscriptions/{enums,schemas}.py unrelated to the review findings, nothing to flag there.

Nothing new surfaced in this pass. The two page diffs are clean additions with no leftover inconsistencies from the fix-up commits.
· branch

[ankitottu]

Redmine epic #158909 — closes the docs half of the AutoPay launch.

Merges the epic branch into dev, which deploys to docs.ottu.dev for review. Nothing reaches docs.ottu.com until it has been signed off there — that is #158915.

What ships

#158910	Developer section at /developers/payments/autopay/ + AutoPayFlowDiagram + glossary terms + payments-index entry
#158912	Business section at /business/autopay/, one long page with a Pattern-A anchor sub-menu
#158913 (partial)	20 customer-portal and notification screenshots from Menna
—	Design spec + execution plan under docs/superpowers/

Both child PRs (#167, #168) already merged here. sidebars.ts was edited once, in the scaffold commit, so the two lanes never touched the same file.

The distinction the whole thing hangs on

With auto_debit the merchant owns the billing schedule, retries and dunning. With auto_pay, AutoPay owns them.

recurring-payments.mdx is the closest existing page and readers will land on the wrong one, so both pages now cross-link with an explicit "use this when".

Facts documented that appear in no ticket

Found by reading autopay/subscriptions/ and by a live betabulk call:

• The autopay request block is write-only — not echoed in the 201. extra.autopay.subscription_id is the merchant's only handle. Verified live: sub_hA1YYmZz1xk8speCiPbOquIP.
• customer_email is required. Omitting it 422s inside AutoPay and surfaces as 400 {"autopay":["AutoPayClient rejected request (422)"]} — reads like an agreement-shape error and is not.
• page-link does not rotate the token; regenerate-page-token revokes. A merchant reaching for regenerate when they meant re-send silently breaks the customer's working link, with no notification to that customer.
• retry_window_days is dead — dropped in migrations/0028_drop_retry_window_days.py. ⚠️#158911's field table still lists it as live with a 1–30 range. That table is also the spec for the enrichment YAML, so it needs correcting there too.
• list returns a slim summary, not full subscription objects.
• The customer page token is signed, not encrypted — the payload is readable base64. Treat the link like a password.

Known gaps, deliberate

Gap	Why
## API Reference is a placeholder	core_backend PR 121 unmerged — static/Ottu_API.yaml has zero autopay occurrences, so <ApiDocEmbed> cannot resolve. Endpoints documented as prose + cURL under ## Guide instead.
Endpoint base path unconfirmed	Samples use AutoPay's own root-mounted paths. Merchants reach these through a Connect proxy whose public path is in PR 121. @yamen — needs your answer.
JWT acquisition undocumented	Five of six endpoints need a Keycloak JWT; the auth guide only covers Api-Key. Flagged in a :::warning on the page rather than papered over.
No merchant dashboard content	It does not exist — REST-API-only this phase, confirmed by @dacian 2026-08-13.
No add-card screenshot	Not captured yet; behaviour written as prose, no image referenced.
No video	Remotion is #158914, decoupled.

Verification

• npm run typecheck ✅ · npm run build ✅
• Both pages adversarially verified by subagents against their tickets' own acceptance criteria: developer 14 PASS / 1 BLOCKED, business 13 PASS
• Checked by hand in Chrome against the local production build — onBrokenLinks is "warn", so a green build proves nothing about navigation:
  • business sidebar anchors 10/10 resolve, developer 5/5, in-page links 21/21
  • every referenced image returns HTTP 200
  • flow diagram renders correctly in light and dark mode
• Every behavioural claim traced to autopay/subscriptions/enums.py, models.py, schemas.py or tasks/_tenant_processors.py

⚠️ One thing to look at before approving

portal-01-summary-active.png is the hero image on the business page and it is a mockup that contradicts the real product. Checked against a live betabulk portal: it shows an invoice Download column (AutoPay stores no invoices), a Pay Now button on an active subscription (Pay Now only exists when past due), two cards both masked *** 1234, and a next-payment date a year adrift from its own history.

The prose no longer describes any of it, but a reader still sees it. Recutting that one image — or a straight recapture from betabulk — is the highest-value screenshot task left. @junaid@Menna

Sign-off needed (#158915)

• @yamen — backend and API accuracy, PR 121, proxy base path
• @ankit — AutoPay behaviour and business accuracy
• @junaid / @Menna — visual review

Do not merge until reviewed on this branch.

[jab3z]

@claude review

[claude]

Claude finished @jab3z's task in 3m 14s —— View job

---

Review complete

• Gather context (PR body, changed files list)
• Read diff (git diff origin/dev...HEAD)
• Review developer AutoPay page + flow diagram
• Review business AutoPay page
• Review sidebars.ts, glossary, cross-links
• Check CLAUDE.md compliance (API base URL constant, merchant_id, cross-linking, etc.)
• Post final review

Note: node_modules isn't installed in this sandbox and installing it wasn't in scope, so I couldn't independently re-run npm run build/npm run typecheck — this review is a manual read of the diff against origin/dev and the repo's CLAUDE.md conventions.

Overall this is a strong, well-verified page pair — the sidebar anchor hygiene (sidebars.ts) all checks out against actual heading IDs on both pages, the <AutoPayFlowDiagram> follows the svg-diagram skill convention correctly (monochrome + 2 accent nodes, light/dark overrides), OTTU_CONNECT_BASE_URL is used consistently instead of hardcoded URLs, and the cross-linking between AutoPay and recurring-payments.mdx is exactly the kind of disambiguation the domain needs. A few things worth a look before merging to dev:

1. "Copy-paste accurate" claim conflicts with the PR's own "base path unconfirmed" gap

docs/developers/payments/autopay/index.mdx:437-441 (API Reference section):

"Every request and response shown above is copy-paste accurate"

But the PR description itself flags "Endpoint base path unconfirmed... Merchants reach these through a Connect proxy whose public path is in PR 121 — @yamen needs your answer." The six subscription-management cURL examples (#step-by-step) hit plain ${OTTU_CONNECT_BASE_URL}/subscriptions/... with no proxy prefix, while the one endpoint you have confirmed (checkout, step 1) is prefixed /b/checkout/v1/pymt-txn/. Since the base path for steps 2–6 is explicitly still pending confirmation, the "copy-paste accurate" claim overstates what's verified — a developer could reasonably build against /subscriptions/... directly and hit 404s once the real proxy path lands. Consider either softening that line or adding the same base-path caveat that's already implicit in the PR's "known gaps" table, so it's visible to a reader on docs.ottu.dev, not just to reviewers on this PR.
Fix this →

2. New glossary terms aren't linked from either new page

src/data/glossary-terms.ts adds Billing Cycle, Dunning, and Subscription, all introduced specifically for AutoPay — but neither docs/developers/payments/autopay/index.mdx nor docs/business/autopay/index.md links to /glossary/ on first use, despite root CLAUDE.md's "no jargon without definition — first use links to the glossary" rule and the developer CLAUDE.md cross-referencing table. (This rule is loosely followed elsewhere in the repo too, so treat this as a nice-to-have rather than a blocker — but since these terms were added for this PR, it's a natural fit to wire them up here.)

3. Two shipped screenshots are never referenced, one contradicts the page copy

git diff --stat shows 20 new business screenshots, but only 18 are referenced from docs/business/autopay/index.md:

• static/img/business/autopay/portal-04-expired.png — the "Expired" step in the state <StepGuide> (docs/business/autopay/index.md:135-138) has no image/imageAlt, even though this exact screenshot exists.
• static/img/business/autopay/cards-01-delete-confirm.png — unreferenced anywhere. This one is worth double-checking specifically: the page states "Saved cards are never deleted... there is no removal step to walk them through" (line 195), but a screenshot named cards-01-delete-confirm strongly implies a delete-confirmation dialog exists in the product. Given the PR already flagged portal-01-summary-active.png as a stale mockup that contradicts the real product, this looks like it could be the same class of issue — either the copy is right and this is a leftover asset that should be dropped, or card deletion does exist and the copy needs correcting. Worth a quick check with @Menna/@junaid alongside the portal-01 fix.

Not re-litigated

The factual claims (write-only autopay block, customer_email 422 behavior, page-link vs regenerate-page-token, dead retry_window_days, slim list summary, signed-not-encrypted token) all match what's described in the PR body as independently verified against autopay/subscriptions/ source and a live betabulk call — I didn't have backend access to re-verify these, so I'm relying on the PR author's stated verification method there.
· branch epic/158909

[ankitottu]

@claude re-review

[claude]

Claude finished @ankitottu's task in 1m 38s —— View job

---

Re-review complete

• Gather context (PR body, prior review, changed files)
• Check what changed since the last review (commit 34e4484)
• Verify the three prior findings were actually resolved
• Fresh pass over the full diff for anything new
• Post final review

Note: node_modules still isn't installed in this sandbox, so I couldn't independently re-run npm run build/npm run typecheck — this is a manual read of git diff origin/dev...HEAD plus the four fix commits added since the first review (b5475bf, 79835e2, 93c1567, 34e4484).

All three points from the first review are resolved cleanly in 34e4484:

1. "Copy-paste accurate" overclaim — fixed. docs/developers/payments/autopay/index.mdx:62-65 now has a dedicated :::warning The path in front of /subscriptions/ isn't final block naming exactly what's unconfirmed (the Connect proxy prefix for Steps 2–6) while explicitly stating headers/bodies/responses/behaviour are accurate, and that Step 1's /b/checkout/v1/pymt-txn/ is stable. The old blanket "copy-paste accurate" line under ## API Reference (line ~444) was replaced with a pointer to that scoped caveat instead of a second overclaim. This is exactly the right fix — it's visible to a reader on docs.ottu.dev now, not just to PR reviewers.

2. Glossary terms unlinked — fixed. Billing Cycle, Dunning, and Subscription are each now linked once per page via /glossary/#term-<id>. Verified the anchor mechanism actually resolves: src/components/GlossarySearch/index.tsx:7,30-31 builds/reads the same term-${id} hash format server-side, and the ids added in src/data/glossary-terms.ts (billing-cycle, dunning, subscription) match what's linked. The commit message's note that Docusaurus's broken-link checker will still flag these as a false positive (same pattern as the existing payment-states/transaction-states pages) checks out.

3. Unreferenced/contradictory screenshots — fixed correctly, not just papered over. Both cards-01-delete-confirm.png and portal-04-expired.png are deleted from the tree (not just dereferenced), so they can't get silently wired back in later. Confirmed no remaining references to either filename anywhere in the repo, and confirmed all 19 remaining business screenshots (20 shipped − 2 dropped − wait, 18 referenced + the dropped 2 = 20 ✓) are each referenced from docs/business/autopay/index.md. The "Expired" step in the state <StepGuide> (docs/business/autopay/index.md:135-138) now correctly has no image/imageAlt at all, matching its terminal-state description instead of showing a fabricated Reactivate button.

One thing worth noting rather than re-flagging: portal-01-summary-active.png (the hero mockup the PR body itself calls out as contradicting the real product) is still in place — that's expected, since the PR description already tracks it as the open "highest-value screenshot task left" pending recapture from betabulk, not something silently missed.

Also scanned the intervening accuracy commit (93c1567, notification keys / list-summary shape / cycle statuses) — it's a good-faith correctness pass against autopay/subscriptions/{enums,schemas}.py unrelated to the review findings, nothing to flag there.

Nothing new surfaced in this pass. The two page diffs are clean additions with no leftover inconsistencies from the fix-up commits.
· branch