Make the repo public

.cursor/skills/authoring-how-to/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: authoring-how-to
+description: Authors and revises in-depth Chargebee integration how-to guides in the reference-architecture repository, following the structure, mermaid-only diagram rule, and writing voice of how-to/integrating-chargebee-webhooks.md. Use when adding or editing any file under how-to/, when asked to write or review a Chargebee how-to or reference-architecture guide, or when documenting a Chargebee integration topic such as webhooks, subscription lifecycle, checkout, invoices, payments, dunning, entitlements, usage metering, tax, or reconciliation.
+---
+
+# Authoring reference-architecture how-tos
+
+The `how-to/` directory holds vetted, in-depth guides on integrating Chargebee into a high-traffic SaaS platform. Each guide gives an architect or developer a design they can build against, plus the operational detail needed to run it. `pointer/` is the working implementation those guides point at.
+
+Read [`how-to/integrating-chargebee-webhooks.md`](../../../how-to/integrating-chargebee-webhooks.md) before writing. It is the structural and tonal reference. Match its shape and voice; do not copy its sentences or reproduce its typos.
+
+## Four rules that override everything else
+
+1. **Everything is code, including diagrams.** Every diagram is a fenced `mermaid` code block committed in the markdown. No images, no screenshots, no ASCII art, no links to Lucid, Miro, Excalidraw, or draw.io. If a design can't be drawn in mermaid, describe it in prose instead of reaching for a picture.
+2. **Verify Chargebee behavior against the live docs.** Never write API names, field names, event types, limits, or product behavior from memory. See [references/chargebee-sources.md](references/chargebee-sources.md).
+3. **Go deep.** These are not quickstarts. A guide that only documents the happy path has failed. Cover the failure modes, the ordering and idempotency and consistency concerns, and the trade-offs behind each recommendation.
+4. **Write like the reference guide, not like a model.** The language rules in [references/language.md](references/language.md) are enforceable, not advisory. Run the validator before finishing.
+
+## Workflow
+
+1. **Fix the scope.** Name the outcome the reader wants and the boundary of the system covered. One guide, one outcome. If the topic is really two outcomes, propose splitting it.
+2. **Research.** Pull the current behavior from Chargebee's docs and API reference, then read the relevant `pointer/` code. Follow [references/chargebee-sources.md](references/chargebee-sources.md). Note the exact URLs you relied on; they become the guide's outbound links.
+3. **Map the design.** Before writing prose, work out: the synchronous path, what moves to asynchronous work, the system of record for each piece of state, every failure path, who retries and what gets acknowledged, and how state is reconciled when things drift.
+4. **Draft.** Copy [assets/how-to-template.md](assets/how-to-template.md) to `how-to/<verb>-<topic>.md` and fill it in. Keep the section order.
+5. **Draw the diagrams.** Follow [references/diagrams.md](references/diagrams.md) for the sequence and flowchart conventions used across the repo.
+6. **Ground the implementation notes.** Open every `pointer/` file you cite and confirm it still does what you say. Label opinionated choices (SQS, Better Auth, Next.js, Postgres) as `pointer`'s choices, not Chargebee requirements.
+7. **Validate.** Run the checker, fix every error, and for each warning either fix it or be able to say why it is a false positive.
+
+    ```bash
+    python3 .cursor/skills/author-ref-arch-how-to/scripts/check_how_to.py how-to/<your-file>.md
+    ```
+
+8. **Register the guide.** Add it to the numbered topic list in [`how-to/README.md`](../../../how-to/README.md).
+9. **Self-review.** Walk the final checklist at the bottom of this file.
+
+## Required structure
+
+Keep this order. Drop a section only when the topic genuinely has nothing to put in it.
+
+| Section | Heading | Contains |
+| --- | --- | --- |
+| Title | `# How to <outcome>` | The outcome, phrased as a task |
+| Intro | (no heading) | Why this matters and what the reader will build, in 2–4 sentences, optionally followed by a short list of concrete reasons |
+| Architecture | `## High level architecture` | One mermaid diagram covering happy path and the failure paths that matter |
+| Guidance | `## Best Practices` | Recommendations organized by responsibility, with `###` subsections for the hard correctness topics |
+| Code | `## Implementation notes` | How `pointer` does it, with links to specific files and what each one does |
+| Launch | `## Go-live checklist` | `- [ ]` questions that can be answered yes or no before deploying |
+
+`Best Practices` keeps its title-case capitalization to match the reference guide. Every other heading is sentence case.
+
+### Intro
+
+Open on the reader's situation, not on the document. The reference guide starts with `One of the first steps when integrating Chargebee using the SDK/API is to setup webhooks. You will need webhooks to:` and then lists three reasons. That is the pattern: a sentence that places the topic in a real integration sequence, then the concrete payoff.
+
+### High level architecture
+
+Lead with the diagram, then explain it in prose dense enough that a reader who skips the diagram still understands the design. Show where trust boundaries sit, where a hand-off becomes durable, what runs asynchronously, and what happens on error.
+
+### Best Practices
+
+Group by responsibility or design decision. For each recommendation, say what to do, why it matters, and what breaks if it is skipped. Where the topic involves retries, duplicates, ordering, concurrency, or partial failure, spell out the semantics rather than gesturing at them.
+
+Promote a genuinely hard correctness problem into its own `###` subsection with its own mermaid sequence. The reference guide does this for out-of-order and dependent events, and that subsection is the most useful part of the document. Drop to `####` for a finer breakdown inside it, as the reference guide does for retry semantics.
+
+### Implementation notes
+
+Open with a short paragraph on how `pointer` wires the topic together, then a bulleted list of files. Each bullet is a link to the file followed by its role and the runtime behavior that matters, for example what acknowledges a message or what happens on a thrown error.
+
+State trade-offs plainly when `pointer` diverges from the recommended production design.
+
+### Go-live checklist
+
+Write each item as a question with a testable answer:
+
+```markdown
+- [ ] Does the worker retry transient failures without acknowledging the message?
+```
+
+Cover configuration, authentication, correctness, failure recovery, observability, security, scale, reconciliation, and ownership as the topic warrants. Reject anything as soft as "Is the integration production-ready?".
+
+## Reference files
+
+- [references/language.md](references/language.md) — the voice, sentence patterns, formatting conventions, and the banned-phrase list. Read this before drafting prose.
+- [references/diagrams.md](references/diagrams.md) — mermaid conventions: participant naming, `alt` blocks for failure paths, when to use `flowchart` over `sequenceDiagram`.
+- [references/chargebee-sources.md](references/chargebee-sources.md) — which documentation site to trust for what, verified entry-point URLs, product-version traps, and the facts that must always be verified rather than recalled.
+- [assets/how-to-template.md](assets/how-to-template.md) — the skeleton to copy into `how-to/`.
+- [scripts/check_how_to.py](scripts/check_how_to.py) — structural and language validator. Run with `--strict` to make warnings fail too.
+
+## Final checklist
+
+- [ ] The title names a concrete outcome, not a subject area.
+- [ ] The intro states the reader's problem in its first sentence and contains no meta-commentary about the document.
+- [ ] Every diagram is mermaid, and the diagram and the prose describe the same system.
+- [ ] Failure paths appear in the architecture diagram, not just in the prose.
+- [ ] Each recommendation carries its rationale and its failure mode.
+- [ ] Delivery and consistency semantics are stated precisely, and "exactly once" is not claimed unless the design proves it.
+- [ ] Chargebee behavior, event types, and field names were checked against the live documentation, and the guide links to the pages a reader would use to verify them.
+- [ ] `pointer`'s technology choices are labelled as choices.
+- [ ] Every repository link resolves and every cited file still plays the stated role.
+- [ ] Checklist items are answerable yes or no before launch.
+- [ ] The draft has no filler transitions, no bolded label on every bullet, no closing summary, and nothing that reads like a template.
+- [ ] `check_how_to.py` reports no errors.

.cursor/skills/authoring-how-to/assets/how-to-template.md

@@ -0,0 +1,139 @@
+# How to <do the thing> with Chargebee
+
+<!--
+Delete every comment in this file before committing.
+Intro: 2-4 sentences. Sentence one places the topic in a real integration sequence
+("One of the first steps when integrating Chargebee ... is ..."). Then say what the
+reader will build or decide. A short list of concrete reasons is optional and only
+earns its place if the items are genuinely parallel. No meta-commentary about the guide.
+-->
+
+<Why this matters, in the reader's terms.> You will need <the thing> to:
+
+* <Concrete outcome one>
+* <Concrete outcome two>
+* <Concrete outcome three, only if there is one>
+
+
+## High level architecture
+
+<!--
+One mermaid diagram. Happy path plus the failure paths that matter. Keep it
+technology-neutral: "Durable Queue/Store", not "SQS". See references/diagrams.md.
+-->
+
+```mermaid
+sequenceDiagram
+    participant cb as Chargebee
+    participant app as App
+    participant queue as Durable <br>Queue/Store
+    participant worker as Worker
+    participant db as Database
+
+    cb->>app: <Real event or call name>
+    activate app
+    note over app: <Validation or decision>
+    app->>queue: Store message
+    alt Error
+        app->>cb: HTTP 5xx (Retry)
+        cb-->>app: Scheduled retry
+    else Success
+        app->>cb: HTTP 2xx (Success)
+    end
+    deactivate app
+
+    queue-)worker: Receive messages
+    activate worker
+    worker-->>db: <Write>
+    alt All OK
+        worker-->>queue: Ack
+    else Retryable error
+        worker->>queue: Error (Retry)
+    else Non-retryable error
+        note over queue: Push to Dead Letter<br>queue/store
+    end
+    deactivate worker
+```
+
+<!--
+Follow the diagram with prose dense enough that a reader who skipped it still
+understands the design: where the trust boundary is, where the hand-off becomes
+durable, what runs asynchronously, what is authoritative.
+-->
+
+
+## Best Practices
+
+<!--
+Group by responsibility or design decision. Each top-level bullet: what to do, why
+it matters, what breaks if it is skipped. Nested bullets only for genuine sequences
+or parallel mechanics. Do not bold a label at the front of every bullet.
+-->
+
+* <Recommendation stated as an action.> <Why, and what fails without it.> It should:
+
+    - <Step one>
+    - <Step two>
+    - <Step three>
+
+* <Recommendation two.> Bold a **new term** on first use, then drop the bold.
+
+* <Recommendation three, covering duplicates, ordering, concurrency, or partial failure. State the delivery semantics precisely.>
+
+
+### <The hardest correctness problem in this topic>
+
+<!--
+Promote a genuinely hard case into its own subsection. Name the failure concretely
+using real Chargebee resource and event names. Add a scenario sequence diagram.
+-->
+
+<Explain the case. Lead with the mechanism, not the vibe.>
+
+```mermaid
+sequenceDiagram
+    participant cb as Chargebee
+    participant app as App
+    participant worker as Worker
+
+    note over cb,worker: <The specific scenario being walked>
+
+    cb->>app: <event>
+    app->>cb: HTTP 2xx
+```
+
+<Rules the implementation must follow, as short imperative sentences.>
+
+
+## Implementation notes
+
+The [`pointer`](../pointer/) app implements <topic> using <the opinionated choice>. <One short paragraph on how the pieces fit together at runtime.>
+
+- [`pointer/<path>`](../pointer/<path>) — <role, and the runtime behavior that matters: what acknowledges, what retries, what happens on a thrown error.>
+
+- [`pointer/<path>`](../pointer/<path>) — <role and behavior.>
+
+<!--
+Label opinionated choices as pointer's choices, not Chargebee requirements. If the
+implementation diverges from the recommended production design, say so and say why.
+-->
+
+
+## Go-live checklist
+
+<!--
+Questions with testable yes/no answers. Cover configuration, authentication,
+correctness, failure recovery, observability, security, scale, reconciliation, and
+ownership as the topic warrants. Nothing as soft as "Is it production-ready?".
+The document ends here. No summary, no conclusion.
+-->
+
+- [ ] <Configuration question?>
+
+- [ ] <Authentication or authorization question?>
+
+- [ ] <Correctness question about duplicates, ordering, or idempotency?>
+
+- [ ] <Failure recovery question about retries and dead-lettering?>
+
+- [ ] <Observability or reconciliation question?>

.cursor/skills/authoring-how-to/references/chargebee-sources.md

@@ -0,0 +1,98 @@
+# Chargebee sources
+
+These guides are read by people who will build against them, so a wrong field name or a stale limit is worse than no guide. Verify every Chargebee-specific claim against the live documentation while drafting.
+
+## Contents
+
+- [Which site for which question](#which-site-for-which-question)
+- [Research procedure](#research-procedure)
+- [Verified entry points](#verified-entry-points)
+- [Facts that must never be written from memory](#facts-that-must-never-be-written-from-memory)
+- [Product version traps](#product-version-traps)
+- [Tooling that speeds up research](#tooling-that-speeds-up-research)
+
+## Which site for which question
+
+| Question | Site |
+| --- | --- |
+| What does this endpoint accept and return? What are the resource attributes, enums, and event types? | [apidocs.chargebee.com](https://apidocs.chargebee.com/docs/api) |
+| How does the product behave? What does this setting do in the dashboard? How do these objects relate? | [chargebee.com/docs](https://www.chargebee.com/docs/billing/2.0/getting-started/object-relationship) |
+
+When product behavior and API reference appear to disagree, cite the API reference for the contract and the product docs for the behavior, and say which is which.
+
+## Research procedure
+
+1. Search the relevant site for the topic. The docs URL scheme is `https://www.chargebee.com/docs/billing/2.0/<section>/<page>`; the API reference is `https://apidocs.chargebee.com/docs/api/<resource>`.
+2. Read the page rather than the search snippet. Snippets routinely drop the qualifier that matters.
+3. **Confirm the URL resolves before citing it.** Documentation pages get reorganized, and a plausible-looking path is often a 404:
+
+```bash
+curl -s -o /dev/null -w "%{http_code}\n" -L "https://apidocs.chargebee.com/docs/api/<resource>"
+```
+
+The validator's `--external` flag checks every outbound link in a finished guide.
+
+4. Link to the specific section or anchor that supports the claim, not to the section landing page. The webhook guide links straight to the event object's out-of-order delivery anchor, which is what makes that claim checkable.
+5. Cross-check against `pointer/`. If the code contradicts the docs, the code is probably behind — investigate before documenting either.
+
+## Verified entry points
+
+Confirmed reachable at the time of writing. Re-check before citing.
+
+**API reference**
+
+- Getting started, authentication, pagination, error model — `https://apidocs.chargebee.com/docs/api`
+- Events and event types — `https://apidocs.chargebee.com/docs/api/events`
+- Event object, including out-of-order delivery — `https://apidocs.chargebee.com/docs/api/events/event-object`
+- Webhooks — `https://apidocs.chargebee.com/docs/api/webhooks`
+- Idempotency — `https://apidocs.chargebee.com/docs/api/idempotency`
+- Error handling and `api_error_code` — `https://apidocs.chargebee.com/docs/api/error-handling`
+- Customers — `https://apidocs.chargebee.com/docs/api/customers`
+- Subscriptions — `https://apidocs.chargebee.com/docs/api/subscriptions`
+- Invoices — `https://apidocs.chargebee.com/docs/api/invoices`
+- Hosted pages — `https://apidocs.chargebee.com/docs/api/hosted_pages`
+- Payment intents — `https://apidocs.chargebee.com/docs/api/payment_intents`
+- Usages — `https://apidocs.chargebee.com/docs/api/usages`
+- Entitlements — `https://apidocs.chargebee.com/docs/api/entitlements`
+
+**Product documentation**
+
+- Object relationship model — `https://www.chargebee.com/docs/billing/2.0/getting-started/object-relationship`
+- Product catalog — `https://www.chargebee.com/docs/billing/2.0/product-catalog/product-catalog`
+- Subscriptions — `https://www.chargebee.com/docs/billing/2.0/subscriptions/subscriptions`
+- Invoices and credit notes — `https://www.chargebee.com/docs/billing/2.0/invoices-credit-notes-and-quotes/invoice-overview`
+- Entitlements — `https://www.chargebee.com/docs/billing/2.0/entitlements/entitlements`
+- Tax — `https://www.chargebee.com/docs/billing/2.0/taxes/tax-overview`
+
+For anything not listed, search the site and verify the URL. Do not extrapolate a path from the pattern.
+
+## Facts that must never be written from memory
+
+- Event type names and the exact set of resources inside `content` for a given event.
+- Attribute names, nesting, and enum values on any resource.
+- Which parameters an endpoint accepts and which are required.
+- Retry schedules, rate limits, page sizes, expiry windows, and any other number.
+- Whether a feature is generally available, gated, or plan-dependent.
+- Anything about a specific payment gateway's behavior.
+
+Stable enough to rely on, and still worth linking:
+
+- The API is REST over HTTPS at `https://{site}.chargebee.com/api/v2/`, authenticated with HTTP Basic using the API key as the username and an empty password.
+- Timestamps are Unix epoch seconds.
+- Single resources come back enveloped (`{"customer": {...}}`); lists come back as `{"list": [...]}` with `next_offset` for pagination.
+- API keys are per-environment: a test-site key is not a live-site key.
+- Webhook events are delivered at-least-once with no ordering guarantee, and `resource_version` is the tiebreaker for staleness.
+
+## Product version traps
+
+- Documentation paths carry the product version (`/docs/billing/2.0/`). Confirm you are reading 2.0 and not an older page surfaced by a search engine.
+- Product Catalog exists in two versions. The newer model uses items and item prices; the older uses plans and addons. Which one applies changes the API calls, the event payloads, and the local schema. State which version a guide assumes.
+- A Chargebee site can run in test or live mode with separate configuration, keys, and webhook endpoints. Guides should say which mode a step applies to.
+- Chargebee sells more than Billing. If a topic touches Retention, Revenue Recognition, or Receivables, name the product explicitly instead of writing "Chargebee".
+
+## Tooling that speeds up research
+
+- API reference pages carry a **Copy for LLM** control that yields the page as clean markdown.
+- The full API is published as an OpenAPI 3.0 document, which is the fastest way to confirm a parameter list exhaustively.
+- Chargebee publishes an MCP server and official agent skills (`npx skills add chargebee/ai`). If either is available in the session, prefer it over scraping pages.
+- **Time Machine** on a test site simulates time-based billing events. Mention it when a guide's testing scenarios depend on renewals, trial expiry, or dunning cycles.