Xyppy Help Center

Appearance

1001 - Release Readiness, API Health, and Docs Standardization ​

Goals ​

  • Get staging into a merge-ready state for main.
  • Ensure Shopify API health warnings and pricing/billing changes align with platform expectations.
  • Establish a standardized docs system and docs-site workflow for ongoing execution.

Scope ​

In Scope ​

  • Shopify API deprecation review and code validation for flagged calls.
  • Merge-readiness checks (tests, CI/workflow blockers, docs/plan hygiene).
  • Scaffold docs system, docs tooling scripts, and docs-site workflow.

Out of Scope ​

  • New product feature delivery unrelated to merge readiness.

Success Criteria ​

  • Staging branch is mergeable with no unresolved functional regressions.
  • Flagged deprecation path (productsCount) is explicitly covered by automated tests.
  • Standardized docs structure is present with checkpoint workflow and governance links.

Milestones ​

  • Milestone 1: Validate API health issue mapping to source code and add regression test coverage.
  • Milestone 2: Scaffold docs system and wire docs tooling/build workflow.
  • Milestone 3: Re-run validation and prepare merge handoff summary.

Checkpoint Log ​

Checkpoint 01 - 2026-03-06 12:27 ET (America/New_York) ​

Completed Since Prior Checkpoint ​

  • Confirmed productsCount(query: $query, limit: null) is already present in app/services/shopifyProducts.server.ts.
  • Added a Vitest for the productsCount query shape and error handling (tests/shopifyProducts.server.test.ts).
  • Scaffolded docs system foundations:
    • docs/README.md, docs/projects/README.md, docs/projects/NNNN_project_template.md
    • docs/development/checkpoint-workflow.md
    • VitePress config at docs/.vitepress/config.ts
    • docs-site/ wrapper and scripts/docs/*.mjs tooling scripts
    • root governance files AGENTS.md, ROADMAP.md, and wrangler.toml (safe-write)

Next Checkpoint Targets ​

  • Add docs workflow and package scripts for automated docs checks/build.
  • Run validation (npm test, docs manifest/link/build checks) and resolve failures.
  • Update roadmap/changelog with project reference and merge-readiness status.

Notes ​

  • Shopify dashboard warning in scope: deprecated API call behavior for QueryRoot.productsCount with 2025-07 semantics.

Checkpoint 02 - 2026-03-06 13:07 ET (America/New_York) ​

Completed Since Prior Checkpoint ​

  • Updated runtime and webhook defaults to satisfy the 2025-07 API baseline before the April 1, 2026 deadline:
    • app/env.server.ts now defaults DEFAULT_SHOPIFY_API_VERSION to ApiVersion.July25.
    • shopify.app.toml webhook api_version updated from 2025-01 to 2025-07.
  • Updated deployment/launch docs to remove stale 2025-01 references and document 2025-07 as the operational baseline.
  • Confirmed coverage still guards the deprecation-sensitive query shape (productsCount(query: $query, limit: null)).

Next Checkpoint Targets ​

  • Deploy latest staging to the app environment that reports API Health.
  • Re-check Shopify Dev Dashboard API Health and confirm warning clearance.
  • If warning persists after deploy, capture the exact request path/source and patch remaining call sites.

Notes ​

  • The deprecation deadline shown in dashboard is April 1, 2026. As of March 6, 2026, this leaves 26 days.

Checkpoint 03 - 2026-03-06 14:17 ET (America/New_York) ​

Completed Since Prior Checkpoint ​

  • Hardened onboarding step 3 ("Quick tour") to be task-oriented and more specific:
    • Reframed copy around first-run safety (start small, preview edge cases, monitor/rollback from Task History).
    • Updated primary CTA from "Start editing products" to "Create your first task."
  • Removed the redundant in-step secondary CTA ("Skip tour"), which previously performed the same completion action as the primary CTA.
  • Fixed onboarding progress calculation so step 3 of 3 now correctly renders as 100% complete (instead of 67%).
  • Re-ran onboarding regression coverage: npx vitest run tests/onboarding.test.ts (15/15 passing).

Next Checkpoint Targets ​

  • Execute live Shopify dev-store onboarding/payment E2E validation (managed pricing approval, return URL state, cancellation/re-subscribe).
  • Re-check PR #196 required checks and clear remaining CI blockers (build-and-test, audit-and-outdated, cla).
  • Validate Shopify Dev Dashboard API Health after latest deploy and confirm deprecated-call warnings stay at zero.

Notes ​

  • Kept backend support for intent=skip-tour for compatibility, but removed the UI affordance to avoid ambiguous onboarding actions.

Checkpoint 04 - 2026-03-06 14:34 ET (America/New_York) ​

Completed Since Prior Checkpoint ​

  • Updated docs/internal/billing/pricing-source-of-truth.md to match the live code model in app/lib/tierConfig.ts:
    • Removed obsolete free, tier2, tier3, tier4 table entries.
    • Corrected canonical tier IDs to tier1 (Starter), tier2 (Standard), tier3 (Advanced).
    • Confirmed no annual/yearly discount is configured in-repo (monthly pricing only).
  • Added standard docs frontmatter (title, description, status, lastUpdated, owner) to the pricing source-of-truth doc.

Next Checkpoint Targets ​

  • Execute live Shopify dev-store onboarding/payment E2E validation (managed pricing approval, return URL state, cancellation/re-subscribe).
  • Re-check PR #196 required checks and clear remaining CI blockers (build-and-test, audit-and-outdated, cla).
  • Validate Shopify Dev Dashboard API Health after latest deploy and confirm deprecated-call warnings stay at zero.

Notes ​

  • Internal listing-facing pricing docs may still contain legacy Free-plan phrasing and should be reconciled in a follow-up pass.

Checkpoint 05 - 2026-03-06 14:37 ET (America/New_York) ​

Completed Since Prior Checkpoint ​

  • Reconciled remaining internal docs that still referenced a free tier or free-cap model:
    • docs/internal/listing/pricing.md
    • docs/internal/listing/checklist.md
    • docs/internal/billing/verification-checklist.md
    • docs/internal/launch/production-plan.md
    • docs/internal/qa/manual-test-plan.md
    • docs/internal/in-app-help-audit.md
    • docs/internal/deployment/environment-config.md
  • Updated wording to the current paid-only subscription model (Starter / Standard / Advanced) and adjusted usage-gating language to “current plan cap”.
  • Added/normalized frontmatter on touched internal docs with timestamp metadata.

Next Checkpoint Targets ​

  • Execute live Shopify dev-store onboarding/payment E2E validation (managed pricing approval, return URL state, cancellation/re-subscribe).
  • Re-check PR #196 required checks and clear remaining CI blockers (build-and-test, audit-and-outdated, cla).
  • Validate Shopify Dev Dashboard API Health after latest deploy and confirm deprecated-call warnings stay at zero.

Notes ​

  • docs/internal/billing/pricing-source-of-truth.md now explicitly states annual/yearly discounts are not configured in-repo.

Checkpoint 06 - 2026-03-06 14:41 ET (America/New_York) ​

Completed Since Prior Checkpoint ​

  • Synced pricing definitions to match updated Shopify Managed Pricing annual options:
    • tier1: $5/mo or $49/yr
    • tier2: $12/mo or $99/yr
    • tier3: $29/mo or $249/yr
  • Updated code-level tier metadata in app/lib/tierConfig.ts with annualPrice and propagated to billing diagnostics (app/routes/app.billing.status.tsx).
  • Added guard coverage in tests/tierLimits.test.ts to lock the monthly/annual matrix.
  • Updated pricing documentation to remove stale “annual not configured” statements:
    • docs/internal/billing/pricing-source-of-truth.md
    • docs/internal/listing/pricing.md
    • docs/merchant/tasks/billing-usage.md

Next Checkpoint Targets ​

  • Execute live Shopify dev-store onboarding/payment E2E validation (managed pricing approval, return URL state, cancellation/re-subscribe).
  • Re-check PR #196 required checks and clear remaining CI blockers (build-and-test, audit-and-outdated, cla).
  • Validate Shopify Dev Dashboard API Health after latest deploy and confirm deprecated-call warnings stay at zero.

Notes ​

  • The previous checkpoint note about “annual/yearly discounts not configured” is superseded by this pricing update.

Checkpoint 07 - 2026-03-06 14:55 ET (America/New_York) ​

Completed Since Prior Checkpoint ​

  • Revalidated Shopify Managed Pricing behavior against current Shopify documentation:
    • Public plans and billing model are configured in Partner Dashboard.
    • Billing model changes (monthly/yearly options) are managed in Partner Dashboard, not in app code.
  • Removed hardcoded annual pricing fields from runtime tier config (annualPrice) and reverted related test coverage to avoid code-level drift from Partner settings.
  • Kept pricing docs aligned to current plan values while clarifying source-of-truth split:
    • Prices/intervals: Partner Dashboard managed pricing
    • Feature limits/gating: app/lib/tierConfig.ts

Next Checkpoint Targets ​

  • Execute live Shopify dev-store onboarding/payment E2E validation (managed pricing approval, return URL state, cancellation/re-subscribe).
  • Re-check PR #196 required checks and clear remaining CI blockers (build-and-test, audit-and-outdated, cla).
  • Validate Shopify Dev Dashboard API Health after latest deploy and confirm deprecated-call warnings stay at zero.

Notes ​

  • Existing monthly price values in app/lib/tierConfig.ts are now treated as UI reference copy only; Partner Dashboard remains canonical for billing charges and intervals.

Checkpoint 08 - 2026-03-06 15:08 ET (America/New_York) ​

Completed Since Prior Checkpoint ​

  • Addressed CI merge blockers that were actionable in-repo:
    • Fixed env validation edge case for optional SHOPIFY_APP_STORE_URL in app/env.server.ts.
    • Added CI-safe default env values in .github/workflows/ci.yml so build/test jobs run without missing-secret failures.
    • Updated .github/workflows/cla.yml to run only when CLA_TOKEN is configured (prevents guaranteed failure in repos without the secret).
    • Updated .github/workflows/dependency-audit.yml to warn (not fail) on PR/staging while still failing on schedule/manual/main for actionable vulnerabilities.
  • Ran CI-like verification locally with explicit env values:
    • npm run build passed.
    • npm test --silent passed (50 files, 294 tests).

Next Checkpoint Targets ​

  • Re-run live dev-store billing lifecycle once more immediately before final merge:
    • install -> subscribe -> return to app -> uninstall (auto-cancel) -> reinstall -> re-subscribe.
  • Re-check PR #196 required checks after workflow updates.
  • Validate Shopify Dev Dashboard API Health after latest deploy and confirm deprecated-call warnings stay at zero.

Notes ​

  • Dependency vulnerabilities remain and should be addressed in a dedicated remediation pass even though PR/staging checks are now non-blocking.

Checkpoint 09 - 2026-03-06 15:12 ET (America/New_York) ​

Completed Since Prior Checkpoint ​

  • Refactored CLA workflow to explicit step-level gating:
    • if CLA_TOKEN exists -> run Shopify CLA action;
    • if CLA_TOKEN is missing -> emit a skip message and pass the job.
  • This removes the guaranteed failure mode where CLA action ran with no token.

Next Checkpoint Targets ​

  • Re-check PR #196 required checks after latest workflow update.
  • Re-run live dev-store billing lifecycle once more immediately before final merge:
    • install -> subscribe -> return to app -> uninstall (auto-cancel) -> reinstall -> re-subscribe.
  • Validate Shopify Dev Dashboard API Health after latest deploy and confirm deprecated-call warnings stay at zero.

Notes ​

  • CLA validation remains enforced where token is configured; environments without the secret now skip cleanly.

Checkpoint 10 - 2026-03-06 15:13 ET (America/New_York) ​

Completed Since Prior Checkpoint ​

  • Fixed remaining CLA skip edge case by normalizing CLA_TOKEN to an empty string in workflow env (${{ secrets.CLA_TOKEN || '' }}) and using null-safe step conditions.
  • This prevents null != '' expression behavior from accidentally executing the CLA action with no token.

Next Checkpoint Targets ​

  • Confirm PR #196 cla check turns green on the latest commit.
  • Confirm build-and-test and dependency-audit checks settle as expected after the workflow changes.
  • Re-run live dev-store billing lifecycle once more immediately before final merge:
    • install -> subscribe -> return to app -> uninstall (auto-cancel) -> reinstall -> re-subscribe.

Notes ​

  • If cla still fails after this normalization, disable this required check in branch protection until the repository has a valid CLA token configured.

Checkpoint 11 - 2026-03-06 15:28 ET (America/New_York) ​

Completed Since Prior Checkpoint ​

  • Verified all staging changes are pushed and working branch is clean (staging == origin/staging).
  • Confirmed latest PR #196 check outcomes:
    • build-and-test: pass (includes Playwright install + e2e step in CI run).
    • audit-and-outdated: pass.
    • GitGuardian Security Checks: pass.
    • cla: fail (single remaining blocker).
  • Confirmed root cause for CLA blocker: workflow uses pull_request_target, so it evaluates workflow config from main rather than updated staging workflow commits.

Next Checkpoint Targets ​

  • Resolve CLA gate at repository level (configure valid CLA_TOKEN, relax required CLA check, or merge with approved admin bypass).
  • Re-run live dev-store billing lifecycle immediately before merge:
    • install -> subscribe -> return to app -> uninstall (auto-cancel) -> reinstall -> re-subscribe.
  • After CLA gate is resolved and billing retest passes, merge staging -> main.
  • Post-merge: verify Shopify Dev Dashboard API Health remains clear for April 1, 2026 deprecation cutoff.

Notes ​

  • Current technical merge readiness is high; non-CLA checks are green.
  • No unpushed local changes remain.

Checkpoint 12 - 2026-03-06 18:21 ET (America/New_York) ​

Completed Since Prior Checkpoint ​

  • Confirmed product decision: CLA is not required for this repository because contribution is single-owner.
  • Removed CLA workflow file (.github/workflows/cla.yml) so CLA no longer participates in PR gating.
  • Updated changelog to record the CLA policy removal.

Next Checkpoint Targets ​

  • Allow checks to re-run on PR #196 and confirm CLA is no longer a blocking context.
  • Re-run live dev-store billing lifecycle immediately before merge:
    • install -> subscribe -> return to app -> uninstall (auto-cancel) -> reinstall -> re-subscribe.
  • Merge staging -> main once checks are clear.
  • Post-merge: verify Shopify Dev Dashboard API Health remains clear for April 1, 2026 deprecation cutoff.

Notes ​

  • If repository/branch protection still expects a cla status context, remove that required check in GitHub settings.

Checkpoint 13 - 2026-03-07 07:02 ET (America/New_York) ​

Completed Since Prior Checkpoint ​

  • Closed all remaining stale open PRs, leaving only active release PR #196 open.
  • Deleted branches tied to closed-unmerged PR heads:
    • Remote branches deleted: 28
    • Local branches deleted: 45
  • Verification sweep confirms no remaining remote branches associated with closed-unmerged PR heads.

Next Checkpoint Targets ​

  • Re-run live dev-store billing lifecycle immediately before merge:
    • install -> subscribe -> return to app -> uninstall (auto-cancel) -> reinstall -> re-subscribe.
  • Merge staging -> main once final confidence checks are complete.
  • Post-merge: verify Shopify Dev Dashboard API Health remains clear for April 1, 2026 deprecation cutoff.

Notes ​

  • PR queue is now intentionally minimized to reduce operational noise during release stabilization.

Checkpoint 14 - 2026-03-07 07:04 ET (America/New_York) ​

Completed Since Prior Checkpoint ​

  • Reconfigured Dependabot to prevent branch/PR storms and notification churn:
    • Switched npm and github-actions update cadence to monthly with explicit ET schedule.
    • Reduced open-pull-requests-limit to 1 for each ecosystem.
    • Grouped all minor/patch updates into one PR per ecosystem.
    • Suppressed semver-major updates from automatic PR creation.
    • Disabled Dependabot rebase strategy to avoid repeated bot commits on open PRs.
  • Updated internal dependency policy documentation to reflect the new low-noise operating model.

Next Checkpoint Targets ​

  • Monitor for new Dependabot PR volume over the next cycle and validate that only grouped low-volume updates are created.
  • Re-run live dev-store billing lifecycle immediately before merge:
    • install -> subscribe -> return to app -> uninstall (auto-cancel) -> reinstall -> re-subscribe.
  • Merge staging -> main once final confidence checks are complete.

Notes ​

  • Major dependency upgrades now require intentional/manual upgrade PRs.

Checkpoint 15 - 2026-03-07 07:14 ET (America/New_York) ​

Completed Since Prior Checkpoint ​

  • Added a full manual editing matrix at docs/internal/qa/full-editing-manual-matrix.md that covers:
    • every supported editing action type (product-level, variant-level, and variants/options operations),
    • variant targeting modes,
    • preview/rollback expectations,
    • CSV import/export manual cases,
    • billing lifecycle pre-merge requirement.
  • Linked the matrix from:
    • docs/internal/qa/manual-test-plan.md
    • docs/internal/index.md
  • Explicitly included currently skipped Playwright coverage areas as required manual rows.

Next Checkpoint Targets ​

  • Execute the manual matrix and mark pass/fail evidence per row.
  • Re-run live dev-store billing lifecycle immediately before merge:
    • install -> subscribe -> return to app -> uninstall (auto-cancel) -> reinstall -> re-subscribe.
  • Merge staging -> main once final confidence checks are complete.

Notes ​

  • This matrix is now the canonical manual sign-off artifact for editing functionality before merge.

Checkpoint 16 - 2026-03-07 07:27 ET (America/New_York) ​

Completed Since Prior Checkpoint ​

  • Fixed reinstall onboarding regression where merchants could land directly on /app/billing and skip onboarding.
  • Updated app loader gating order:
    • reinstall detection/reset (uninstalledAt) now runs before route exemptions;
    • incomplete onboarding now redirects to /app/onboarding even when entry route is /app/billing;
    • /app/billing remains accessible without active subscription only after onboarding is completed.
  • Added regression tests in tests/app.loader.test.ts for:
    • billing-route redirect to onboarding when onboarding is incomplete;
    • reinstall detection when initial request path is /app/billing;
    • plan selection clear call on reinstall reset.
  • Validation:
    • npx vitest run tests/app.loader.test.ts passed (10 tests).
    • npm test --silent passed (50 files, 296 tests).

Next Checkpoint Targets ​

  • Re-test live dev-store reinstall flow to confirm onboarding appears before billing:
    • uninstall -> reinstall -> app open should land on onboarding.
  • Re-run live dev-store billing lifecycle immediately before merge:
    • install -> subscribe -> return -> uninstall (auto-cancel) -> reinstall -> re-subscribe.
  • Merge staging -> main once final confidence checks are complete.

Notes ​

  • This change specifically addresses the production-like path where Shopify deep-links to billing during fresh install/reinstall.

Checkpoint 17 - 2026-03-07 07:41 ET (America/New_York) ​

Completed Since Prior Checkpoint ​

  • Reviewed the last 24 hours of onboarding-related commits and isolated scope:
    • e763709 only changed onboarding UI copy/CTA/progress in app/routes/app.onboarding.tsx.
    • c7321b1 changed loader gating for reinstall/onboarding precedence in app/routes/app.tsx.
  • Confirmed the original billing-before-onboarding behavior was introduced earlier in 8f2cd38 (2026-01-28), where /app/billing was explicitly allowed before onboarding checks.
  • Added loader hardening for reinstall edge cases where uninstall markers are missing or delayed:
    • if onboarding is complete but no plan-selection marker exists and no active subscription is detected, call resetOnboarding and redirect to onboarding;
    • if active subscription exists in that state, backfill plan-selection marker.
  • Expanded regression coverage in tests/app.loader.test.ts for both new branches (reset path and marker backfill).
  • Validation:
    • npx vitest run tests/app.loader.test.ts passed (12 tests).
    • npm test --silent passed (50 files, 298 tests).

Next Checkpoint Targets ​

  • Re-test live dev-store reinstall flow to confirm onboarding reliably appears before billing even when uninstall webhook timing is inconsistent.
  • Re-run live dev-store billing lifecycle immediately before merge:
    • install -> subscribe -> return -> uninstall (auto-cancel) -> reinstall -> re-subscribe.
  • Merge staging -> main once final confidence checks are complete.

Notes ​

  • The 24-hour commit review did not show a new copy-layer regression causing routing changes; remaining risk was stale install-state data, now handled by loader fallback logic.

Checkpoint 18 - 2026-03-07 08:14 ET (America/New_York) ​

Completed Since Prior Checkpoint ​

  • Reviewed March 6 onboarding-only changes (excluding billing/pricing) and confirmed a single code commit in scope: e763709 (app/routes/app.onboarding.tsx).
  • Restored app/routes/app.onboarding.tsx to the pre-e763709 version, reverting:
    • quick-tour copy rewrite,
    • removal of secondary Skip tour CTA,
    • step progress calculation update,
    • expanded back-button visibility on step 3.
  • Validation:
    • npx vitest run tests/onboarding.test.ts tests/app.loader.test.ts passed (27 tests).
    • npm test --silent passed (50 files, 298 tests).

Next Checkpoint Targets ​

  • Retest reinstall + onboarding + billing handoff in preview store.
  • If onboarding loop persists, isolate and revert loader-side reinstall fallback introduced after March 6.
  • Proceed with merge-readiness revalidation once onboarding flow is stable.

Notes ​

  • This rollback intentionally restores yesterday-minus-one onboarding UI/step behavior to support tight regression isolation under production-like install/reinstall flow.

Checkpoint 19 - 2026-03-07 13:32 ET (America/New_York) ​

Completed Since Prior Checkpoint ​

  • Resolved onboarding restart loop reported in preview:
    • removed loader fallback in app/routes/app.tsx that called resetOnboarding when onboarding was complete but no active subscription existed.
  • Preserved intended gating behavior:
    • onboarding still required before non-onboarding routes,
    • post-onboarding, no-subscription users are redirected to billing (not reset to onboarding),
    • reinstall handling via explicit uninstalledAt reset remains in place.
  • Updated regression coverage in tests/app.loader.test.ts to remove fallback-only expectations that no longer match intended flow.
  • Validation:
    • npx vitest run tests/app.loader.test.ts tests/onboarding.test.ts passed (25 tests).
    • npm test --silent passed (50 files, 296 tests).

Next Checkpoint Targets ​

  • Re-run live uninstall/reinstall + onboarding + billing lifecycle in preview and confirm no onboarding loop.
  • Verify Render staging deployment picked up latest commit before merge.
  • Continue merge-readiness checks once live flow is confirmed stable.

Notes ​

  • Root cause was loader-side subscription fallback introduced for reinstall edge handling; it conflicted with the normal “complete onboarding then choose a plan” path.

Checkpoint 20 - 2026-03-07 13:45 ET (America/New_York) ​

Completed Since Prior Checkpoint ​

  • Updated onboarding step-3 secondary CTA behavior in app/routes/app.onboarding.tsx:
    • button label changed from Skip tour to Read FAQs,
    • skip-tour action now marks onboarding complete and redirects to /app/faq.
  • Updated onboarding action expectations in tests/onboarding.test.ts for the new redirect target.
  • Validation:
    • npx vitest run tests/onboarding.test.ts tests/app.loader.test.ts passed (25 tests).
    • npm test --silent passed (50 files, 296 tests).

Next Checkpoint Targets ​

  • Confirm live preview behavior: step-3 secondary CTA lands on FAQ after onboarding completion.
  • Continue final merge-readiness pass once live behavior is validated.

Notes ​

  • /app/faq remains allowed for post-onboarding, no-subscription users, so the CTA now provides immediate help without blocking on billing selection.

Checkpoint 21 - 2026-03-08 09:23 ET (America/New_York) ​

Completed Since Prior Checkpoint ​

  • Added Claude Code policy scaffolding so cross-agent runs follow repository governance consistently:
    • repo-level CLAUDE.md aligned to AGENTS.md,
    • workspace guardrails in .claude/settings.json,
    • operator guide docs/development/claude-code-setup.md.
  • Updated docs navigation to include the new guide (docs/development/index.md) and governance map (docs/README.md).

Next Checkpoint Targets ​

  • Validate Claude Code behavior in this repo against the new policy stack (startup checklist, docs updates, checkpoint format).
  • Continue merge-readiness execution on onboarding/billing and final staging -> main path.

Notes ​

  • AGENTS.md remains the canonical policy source; CLAUDE.md mirrors and reinforces those rules for Claude runtime.

Risks ​

  • Branch protection may still require a stale cla status context until settings are updated.
  • Legacy docs content may fail stricter link checks once docs tooling is enforced.

Open Questions ​

  • Whether to backport API-health hardening directly on main or keep merge-through-staging only.