engsys 1.0.0

package/stacks/db/mongo/skills/mongo-conventions/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: mongo-conventions
+description: MongoDB conventions for this repo — async access via Motor, append-only data-lake discipline, and provenance on every datum. Use when reading/writing Mongo collections, adding ingest or transform pipelines, designing indexes, building an embedding/vector store on Mongo, or reasoning about which data is the system of record.
+---
+
+# MongoDB Conventions
+
+Applies to: any code touching MongoDB in this repo (storage layers, ingest scripts, transforms, API routes).
+
+> Naturalize: confirm the driver, database name, and the system-of-record collection(s) in `CLAUDE.md`.
+
+## Async access (Motor)
+
+- Use the **async driver (Motor)** end-to-end in async services; `await` every DB call. Don't block the event loop with the sync `pymongo` client in request paths.
+- The sync `pymongo` client is acceptable only for things Motor doesn't cover (e.g. GridFS) or for offline scripts — keep it off the hot path.
+- Centralize connection setup: build the connection string from the environment (`MONGODB_URI` / `DATABASE_URL`, falling back to a local default), and detect localhost to skip TLS for dev.
+- Create collections and indexes idempotently in an `initialize_collections()`-style routine: check `list_collection_names()` first, then `create_index(...)`. Mark uniqueness explicitly (`unique=True`) on natural keys (e.g. `content_id`).
+- Guard in-memory caches (vector indexes, derived state) with an `asyncio.Lock` so concurrent requests don't rebuild them simultaneously.
+
+```python
+from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorDatabase
+
+client: AsyncIOMotorClient = AsyncIOMotorClient(connection_string)
+db: AsyncIOMotorDatabase = client[db_name]
+await client.admin.command("ping")          # verify connectivity
+await db.content_raw.create_index("content_id", unique=True)
+docs = await db.content_chunks.count_documents({})
+```
+
+## Append-only lake discipline
+
+When the source data is expensive to acquire (paid APIs, rate-limited crawls, one-shot captures), keep a **raw lake collection that is the system of record** and treat everything downstream as a replayable transform:
+
+- **Fetch once, keep forever.** Write raw payloads (with original structure and timestamps) into a lake collection (e.g. `*_lake` / `content_raw`). **Never re-fetch what's already in the lake** — re-fetching spends real money/quota.
+- **Transforms are replayable and never destructive to the lake.** Chunking, extraction, tagging, embedding all read from the lake and write to *derived* collections. If a derived collection is lost, you can rebuild it for free from the lake.
+- **Budget every acquisition run.** Acquisition spends a finite credit allowance; downstream transforms are cheap/free (often local). Make that asymmetry explicit in scripts and logs.
+- A lost derived cache should be an inconvenience, not a catastrophe — design caches to be rebuildable rather than precious.
+
+## Provenance on every datum
+
+- **Every stored datum carries its source + timestamp.** Identity fields, extraction results, tags, and derived facts all record where they came from and when. The UI renders provenance; the pipeline must preserve it through every transform.
+- **`null` over a guess.** When a field can't be confidently determined, store `null` rather than a plausible-but-wrong value. Known priors are hints for an extractor, never hard fallbacks (e.g. a likely author is a prior, not a default — exceptions exist).
+- **Couple derived artifacts to their generator.** Vectors/embeddings are only comparable when query and corpus come from the *same* model. Funnel all query-side embedding through one code path; changing the model requires re-deriving the whole corpus (re-embed + re-index + re-tag) plus recalibrating any model-specific thresholds. Treat the model id as part of the data's provenance.
+- **Aggregate numbers link back to primary sources.** Any rolled-up count or score should be traceable to the underlying documents.
+
+## Indexing & schema
+
+- Index the fields you filter/sort on (`source_type`, `speaker`/owner, tenant/owner keys); add a unique index on natural identifiers.
+- For text search, combine a `$text` index with vector retrieval and fuse with a rank-combination strategy (e.g. RRF) rather than relying on one signal.
+- Store large blobs in GridFS (or external object storage) above a size threshold rather than inlining megabytes into documents.
+
+## Operational notes
+
+- **Restart long-running readers after offline ingest** if they hold an in-memory index — a separate ingest process won't invalidate the running server's cache.
+- **Re-derive after bulk ingest** — new raw rows arrive without derived tags/embeddings; run the tagging/embedding transform after any bulk add.
+- Back up the lake (it's the irreplaceable part); derived collections are rebuildable by design.
+
+## Hard-won lessons
+
+(MongoDB Atlas-specific — only relevant when the cluster is hosted on Atlas.)
+
+### Flex/M0 clusters can't do private endpoints or peering
+**Symptom:** You designed a private DB path (Private Endpoint / VNet) but Atlas
+won't let you create one on the cluster.
+**Cause:** Private endpoints and network peering are **dedicated-tier (M10+)**
+features; Atlas Flex and M0 support IP-allowlist connectivity only.
+**Fix:** If the connection must be private, M10+ dedicated is a hard prerequisite,
+not just a storage upgrade. On Flex, interim connectivity is IP-allowlist only.
+
+### The Atlas SRV subdomain is per-CLUSTER, not per-project
+**Symptom:** After recreating a cluster, the app can't connect — DNS/SRV resolution
+points at the old host.
+**Cause:** The SRV connection-string subdomain (e.g. `…ijcgrnb…` → `…75tne5…`)
+changes whenever the cluster is recreated; it is per-cluster, not per-project. The
+DB user and IP access list are project-scoped and carry over, masking the change.
+**Fix:** After any cluster recreation, update the connection string in **both** env
+vars/`.env` **and** secret stores. Key your config off the immutable project ID, not
+the (renamable) project name.
+
+### Disk autoscaling blocks writes while scaling — size disks for bulk restores
+**Symptom:** A large restore aborts mid-way with `DiskUseThresholdExceeded`.
+**Cause:** Atlas disk auto-scaling **blocks writes while it scales**, so a restore
+that crosses the threshold stalls — and transient journal/firehose overhead can spike
+usage well above the settled corpus size.
+**Fix:** For bulk restores, set a **generous fixed disk** with auto-scaling **off**
+(e.g. 32 GB for a ~6 GB corpus). Atlas disks don't shrink, so the chosen size is a
+permanent floor — pick deliberately.
+
+### In-place tier upgrades can hang and auto-revert — prefer fresh + restore
+**Symptom:** An in-place Flex→M10 upgrade runs ~1h in `UPDATING`, then Atlas
+auto-reverts to the old tier on timeout.
+**Cause:** In-place tier transitions are not reliable and can be system-aborted;
+data survives but the upgrade doesn't land.
+**Fix:** When a local/dump master of record exists (so re-restore is cheap),
+**provision a clean target cluster** (via IaC) and **restore from a dump** rather
+than upgrading in place. Remember the SRV subdomain changes (see above).

package/stacks/db/prisma/claude.fragment.md

@@ -0,0 +1,49 @@
+<!-- pack: db/prisma -->
+## Database — Prisma + shared package
+
+Prisma schema + generated client, shared across backend services as a workspace package (e.g. `@org/database`). See the `docker-database-package-copy` skill for the container-build discipline summarized below.
+
+> Naturalize: record the database-package path, package name, and DB engine (Postgres assumed below) in Project facts.
+
+### Migration workflow
+
+**Never** run `prisma migrate deploy` against a shared environment (dev/staging/prod) from a laptop — CI only.
+
+Local loop:
+
+1. Edit `schema.prisma`.
+2. `npx prisma generate` (or the repo's `db:generate` script).
+3. Write the code that uses the new shape.
+4. Push the branch.
+5. CI opens a migration PR; review the generated SQL.
+6. Merge — auto-deploy follows.
+
+### Schema conventions
+
+- **Naming**: camelCase fields in Prisma, snake_case in the DB via `@map`.
+- **IDs**: UUID `@id @default(uuid())`.
+- **Soft delete**: `deletedAt DateTime?` on tables that need it; default queries filter out soft-deleted rows.
+- **Timestamps**: timezone-aware with explicit precision (Postgres: `@db.Timestamptz(3)`).
+- **Tenant scoping**: every multi-tenant table has `tenantId String` + `@@index([tenantId])`, enforced at the API gateway (e.g. a tenant-context interceptor).
+- **Migrations must be backward-compatible** — services deploy independently of migrations, so old code must still work with the new schema. Add in one release; drop a release later.
+- **JSON-preference columns are single-purpose** — give each per-entity runtime flag its own JSONB column rather than a god-`preferences` blob, so analytics queries hit a focused GIN index and migrations stay narrow. Pair a `?`-queried column with a `USING GIN` index.
+- **Key-style flag naming**: keys inside JSON-preference columns follow `{surface}_{action}_v{N}` (e.g. `recs_kpi_confirm_v1`); bump `vN` to re-surface rather than reusing a key. Document the convention in the model-field comment.
+
+### Docker COPY discipline
+
+Each consumer service Dockerfile copies **specific** TypeScript files from the database package, not the whole tree:
+
+```dockerfile
+COPY services/database/index.ts ./services/database/
+COPY services/database/types.ts ./services/database/
+```
+
+When you add a new `.ts` file under the database package **and export it through `index.ts`**, every Dockerfile that builds the package needs a matching `COPY` line. Missing COPY → CI fails with `TS2307` even though the local full-tree build passes. Before pushing a new exported file:
+
+```bash
+rg 'COPY services/database/' services/*/Dockerfile   # find all consumers
+# add a COPY line to every match, then optionally smoke-build one:
+docker build -f services/<service>/Dockerfile -t db-probe .
+```
+
+**Pre-push gate:** when the Prisma schema is touched, run `prisma generate && <build>`, then rebuild dependent services.

package/stacks/db/prisma/skills/docker-database-package-copy/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: docker-database-package-copy
+description: When adding or changing TypeScript under the shared database package that index.ts re-exports, update every service Dockerfile's COPY list or the container build fails with TS2307. Use for database-package modules, Dockerfile edits, or "works locally but the container build breaks".
+---
+
+# Docker COPY list for the shared database package
+
+Applies to monorepos where a shared Prisma/database package is consumed by multiple containerized services, and each service Dockerfile copies **specific** source files (not the whole tree).
+
+> Naturalize: replace `services/database` with this repo's database-package path and the package name in `CLAUDE.md`.
+
+## Trigger
+
+- New or renamed source file under the database package **reachable from** its `index.ts`.
+- A PR touches the database package's `index.ts` **and** a service `Dockerfile`.
+
+## Do this
+
+1. Find every Dockerfile that copies database sources:
+   ```bash
+   rg 'COPY services/database/' services -g Dockerfile
+   ```
+2. For each **new** source file the package needs, add **once per Dockerfile** that copies database sources:
+
+   ```dockerfile
+   COPY services/database/<filename>.ts ./services/database/
+   ```
+
+   Keep the block with the other `services/database/*.ts` COPY lines.
+
+3. Prefer a quick smoke build before pushing:
+   ```bash
+   docker build -f services/<any-service>/Dockerfile -t probe .
+   ```
+
+## Why
+
+Container images only contain explicitly copied files. A local `pnpm build` uses the full repo tree; **Docker does not**. A missing COPY line surfaces as `TS2307: Cannot find module '.../services/database/<file>'` in CI even though the local build passes.
+
+**Doesn't apply to:** Prisma-only files, CLI-only scripts, anything under the database package that isn't re-exported via `index.ts`.
+
+## Canonical doc
+
+The pack's `claude.fragment.md` (and the rendered `CLAUDE.md`) carries the rest of the Prisma + Docker workflow. If the repo mirrors rules into a Cursor ruleset, keep them in sync.

package/stacks/db/prisma/skills/prisma-conventions/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: prisma-conventions
+description: Prisma ORM conventions for this repo — schema/migration discipline, constraints Prisma can't express, and the @@map/@map gotcha that bites $queryRaw. Activate when writing or reviewing Prisma schema (schema.prisma), migrations, generated-client usage, or raw SQL through Prisma ($queryRaw/$executeRaw), or when debugging P2002 unique-constraint errors or "relation does not exist" at runtime.
+---
+
+# Prisma Conventions
+
+Applies to any code touching Prisma in this repo — `schema.prisma`, migrations under
+`prisma/migrations/`, the generated client, and raw SQL via `$queryRaw`/`$executeRaw`.
+
+> Naturalize: confirm the schema path, datasource provider, and the database-package
+> location in `CLAUDE.md`.
+
+## Hard-won lessons
+
+### Prisma can't express partial / conditional unique constraints
+**Symptom:** You need uniqueness only under a condition (e.g. unique email *among
+non-deleted rows*, or unique slug *per tenant where active*), but `@@unique` applies
+unconditionally and rejects legitimate rows.
+**Cause:** Prisma's schema DSL has no syntax for partial/filtered unique indexes —
+`@@unique` maps to a plain `UNIQUE` constraint with no `WHERE`.
+**Fix:** Hand-write the index in a migration —
+`CREATE UNIQUE INDEX … ON … (…) WHERE …;` — and keep it out of the schema's
+`@@unique`. Because Prisma doesn't model it, catch the violation in the service layer
+by handling the **P2002** error code rather than relying on schema-level validation.
+
+### `$queryRaw` uses DB names (@@map/@map), not Prisma model names
+**Symptom:** Mocked/unit tests pass, but against a real database `$queryRaw` /
+`$executeRaw` throws `relation "User" does not exist` (or a missing-column error).
+**Cause:** Raw SQL **bypasses the ORM** and goes straight to Postgres. Prisma model
+and field names are a client-side abstraction; the actual table/column names are the
+`@@map`/`@map` values from the schema (e.g. model `User` → table `users`). Mocks
+don't hit the DB, so they never reveal the mismatch.
+**Fix:** In any raw SQL, reference the **mapped** table and column names (the
+`@@map`/`@map` values), never the Prisma model/field names. Grep the schema for the
+relevant `@@map`/`@map` before writing the query, and prefer an integration test that
+hits a real database for any raw-SQL path.

package/stacks/domain/mobile-growth/skills/apple-ads/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: apple-ads
+description: "Understand Apple Ads and App Store acquisition mechanics. Use when evaluating Apple Search Ads / Apple Ads placements, campaign structure, keyword strategy, custom product pages, customer type targeting, attribution via AdServices or AdAttributionKit, App Store creative alignment, or Apple app-growth cost planning such as CPT, CPA, ROAS, and budget scenarios."
+---
+
+# Apple Ads
+
+Use this skill when reasoning about paid growth in the App Store ecosystem.
+It is for **Apple Ads** strategy and operations, not StoreKit billing or app
+review.
+
+## When to Use This Skill
+
+- The user asks about Apple Search Ads / Apple Ads.
+- You need to explain App Store ad placements or campaign structure.
+- You need to compare Apple acquisition costs, CPT, CPA, CPI, or ROAS.
+- You need to reason about custom product pages, ad variations, or keyword
+  strategy.
+- You need to refresh Apple Ads guidance from official docs or recent
+  benchmark sources.
+
+## What Exists in the Apple Ads Ecosystem
+
+As of 2025-2026, the practical Apple app-growth stack is:
+
+- **Search Results ads**: the highest-intent App Store placement; users have
+  already typed a query.
+- **Search Tab ads**: discovery before the user searches; broader reach,
+  lower intent.
+- **Today Tab ads**: premium awareness placement on the App Store front page;
+  best for launches, tentpole moments, or large bursts.
+- **Product Pages ads**: contextual reach in the "You Might Also Like" area
+  on app product pages.
+- **Custom Product Pages (CPPs)**: App Store landing pages tailored to
+  keyword themes, feature themes, geographies, or campaigns.
+- **Ad variations**: connect different campaign themes to different CPPs.
+- **AdServices attribution API**: the main deterministic measurement API for
+  Apple Ads itself.
+- **AdAttributionKit**: privacy-preserving attribution for broader ad
+  measurement and postback handling outside the older SKAdNetwork mindset.
+
+## How Apple Ads Works Operationally
+
+### Placement Strategy
+
+- Treat **Search Results** as the core direct-response channel.
+- Treat **Search Tab** and **Today Tab** as upper-funnel or launch support,
+  then judge them by downstream quality, not raw volume.
+- Treat **Product Pages** as contextual conquesting and adjacent-category
+  discovery.
+
+### Campaign Structure
+
+Apple's best-practice structure is still the right default:
+
+1. **Brand**: your app name, company name, and close brand variants.
+2. **Category**: high-intent non-brand keywords describing the job your app
+   does.
+3. **Competitor**: competitor app names and adjacent alternatives.
+4. **Discovery**: Search Match plus broad match to mine new terms.
+
+Keep these separated so you can:
+
+- see what you are actually buying,
+- protect brand cheaply,
+- prevent competitor and discovery traffic from muddying performance, and
+- move proven search terms into exact-match campaigns with tighter bidding.
+
+### Keywords and Search Terms
+
+- **Exact match** belongs in Brand, Category, and Competitor campaigns.
+- **Broad match** belongs mostly in Discovery.
+- **Search Match** is a mining tool, not a substitute for campaign structure.
+- Use **negative keywords** aggressively to stop overlap and irrelevance.
+- Review the **search terms report** regularly and promote winners out of
+  Discovery.
+
+### Audience Refinements
+
+Apple Ads audience settings matter, but search intent usually matters more.
+
+Use refinements when there is a real reason:
+
+- **Customer type**: new users, returning users, or users of your other apps.
+- **Device**: iPhone vs iPad when monetization or conversion differs.
+- **Location**: only when the app or offer is meaningfully geo-specific.
+- **Demographics**: use carefully; intent usually beats inferred profile data.
+
+### Creative and Landing Surface
+
+- Do not point every campaign at the default product page.
+- Build **Custom Product Pages** around specific feature or keyword themes.
+- Match screenshots, preview video, subtitle, and promotional text to the
+  user's likely reason for tapping.
+- Use **ad variations** to map keyword clusters or campaigns to the right CPP.
+- Treat CPPs as a conversion lever, not just a merchandising asset.
+
+## Cost Model and Planning Concepts
+
+### Core Buying Logic
+
+- Apple Ads is an **auction system**.
+- In **manual bidding**, model around **max CPT** for the search-led parts of
+  the system.
+- In **automated bidding** for eligible search-results campaigns, model around
+  **Target CPA / Maximize Conversions**.
+- Budgeting still needs enough volume for the algorithm to learn; underfunded
+  campaigns usually produce noisy, misleading results.
+
+### Practical Metrics
+
+- **CPT**: cost per tap; the direct bid/control concept for search-led buying.
+- **TTR**: tap-through rate; use it to judge keyword and creative relevance.
+- **Conversion rate**: store tap to install.
+- **CPA / CPI**: acquisition cost; what finance and growth actually care about.
+- **ROAS**: use when the app has meaningful post-install revenue data.
+
+### Directional Cost Expectations
+
+Use benchmark numbers as directional, not as promises. Apple does not publish
+market-average costs.
+
+- Search Results is usually the most efficient Apple placement because intent
+  is highest.
+- Search Tab and Today Tab are typically broader-reach and lower-intent, so
+  they need different success criteria.
+- US, Games, Finance, and other competitive categories are materially more
+  expensive than lower-intent regions and softer categories.
+
+Use [references/benchmark-notes.md](references/benchmark-notes.md) for working
+benchmark ranges and caveats.
+
+## Attribution and Measurement Reality
+
+- For **Apple Ads itself**, start with the **AdServices attribution API**.
+- For broader privacy-preserving install and re-engagement measurement on iOS,
+  understand **AdAttributionKit**.
+- Treat **SKAdNetwork** as legacy context you may still encounter, not the only
+  framing.
+- **ATT** still constrains what other networks can do; Apple Ads benefits from
+  its first-party App Store position.
+- For revenue optimization, do not stop at installs. Join Apple Ads data with
+  in-app revenue, renewal, and retention data before making big spend calls.
+
+## Operational Advice
+
+- Defend brand terms first. Letting competitors buy your brand is unforced
+  waste.
+- Separate discovery from exploitation. Discovery finds terms; exact-match
+  campaigns scale them.
+- Use CPPs wherever search intent clearly differs by theme or feature.
+- Judge Search Tab and Today Tab on blended incremental value, not on direct
+  install cost alone.
+- Revisit budget caps before declaring a campaign "bad"; many Apple Ads
+  campaigns are just underfed.
+- Mine returning users separately if reacquisition economics are strong.
+
+## Common Mistakes
+
+- Mixing brand, category, competitor, and discovery traffic in one campaign.
+- Running Discovery forever without graduating winning terms.
+- Using the default product page for every keyword theme.
+- Evaluating all placements with the same KPI.
+- Treating Apple Ads installs as automatically high quality without checking
+  retention, trial start, renewal, or payer mix.
+- Assuming ATT-era attribution means "measurement is impossible" instead of
+  building a practical first-party reporting loop.
+
+## Refresh Workflow
+
+When this skill may be stale:
+
+1. Read [references/official-links.md](references/official-links.md) first.
+2. Re-check Apple Ads help pages for placements, bidding, attribution, and
+   reporting definitions.
+3. Re-check Apple developer docs for CPPs, Apple Ads APIs, and
+   AdAttributionKit.
+4. Use benchmark sources only to set directional priors, never as hard budget
+   guarantees.
+
+## References
+
+- [Official links](references/official-links.md)
+- [Benchmark notes](references/benchmark-notes.md)

package/stacks/domain/mobile-growth/skills/apple-ads/references/benchmark-notes.md

@@ -0,0 +1,47 @@
+# Apple Ads Benchmark Notes
+
+Apple does not publish market-average CPT, CPA, or ROAS benchmarks. Use the
+sources below as directional planning inputs only.
+
+## Practical Benchmark Heuristics
+
+- **Search Results** is usually the most efficient Apple placement because user
+  intent is explicit.
+- **Search Tab** and **Today Tab** tend to look worse on direct CPA but can be
+  useful for awareness, launches, and broader brand capture.
+- Expect large variation by:
+  - country,
+  - category,
+  - seasonality,
+  - brand strength,
+  - product-page conversion quality.
+
+## Common Directional Ranges Seen in 2025-2026 Reporting
+
+- Global median **Search Results CPT** is often reported near the low-
+  single-dollar range.
+- US **Search Results CPT** is often materially higher than global median.
+- Highly competitive categories such as **Games** and **Finance** often cost
+  multiples of softer categories.
+- Search-led install conversion rates are usually far better than non-search
+  placements.
+
+These are not commit-worthy forecast numbers; they are sanity-check inputs.
+
+## Recommended Third-Party Refresh Sources
+
+- AppTweak Apple Ads benchmarks: https://www.apptweak.com/en/aso-blog/apple-ads-benchmarks
+- MobileAction Apple Search Ads benchmark report: https://www.mobileaction.co/report/apple-search-ads-2025-benchmark-report/
+- SplitMetrics Apple Search Ads guides: https://splitmetrics.com/blog/apple-search-ads/
+
+## How to Use Benchmarks Safely
+
+- Build **base / upside / downside** acquisition scenarios.
+- Use benchmarks to detect obviously unrealistic plans, not to set exact bids.
+- Always anchor final decisions to your own:
+  - tap-through rate,
+  - install conversion rate,
+  - trial or purchase conversion,
+  - payback period,
+  - 30-day retention,
+  - renewal or payer quality.

package/stacks/domain/mobile-growth/skills/apple-ads/references/official-links.md

@@ -0,0 +1,53 @@
+# Apple Ads Official Links
+
+Use these first when refreshing the skill.
+
+## Core Apple Ads
+
+- Apple Ads home: https://ads.apple.com/
+- Apple Ads help center: https://ads.apple.com/help
+- App Store ad placements overview: https://ads.apple.com/app-store/help/ad-placements/0081-ad-placement-options
+- Today Tab placement: https://ads.apple.com/app-store/help/ad-placements/0083-today-tab
+- Apple Ads best practices hub: https://ads.apple.com/app-store/best-practices
+
+## Campaign Design and Optimization
+
+- Campaign structure: https://ads.apple.com/app-store/best-practices/campaign-structure
+- Manual bidding: https://ads.apple.com/app-store/best-practices/manual-bidding
+- Maximize Conversions: https://ads.apple.com/app-store/best-practices/maximize-conversions
+- Ad variations: https://ads.apple.com/app-store/best-practices/ad-variations
+- Redownloads / returning users: https://ads.apple.com/app-store/best-practices/redownloads
+- Recommendations: https://ads.apple.com/app-store/best-practices/recommendations
+
+## Keywords, Targeting, and Budget
+
+- Keyword match types: https://ads.apple.com/app-store/help/keywords/0059-understand-keyword-match-types
+- Negative keywords: https://ads.apple.com/app-store/help/keywords/0060-use-negative-keywords
+- Search Match: https://ads.apple.com/app-store/help/campaigns/0006-understand-search-match
+- Audience settings: https://ads.apple.com/app-store/help/ad-groups/0021-modify-audience-settings
+- Manage budgets: https://ads.apple.com/app-store/help/bids-and-budget/0016-manage-budgets
+
+## Measurement and Reporting
+
+- Measuring ad performance: https://ads.apple.com/app-store/help/attribution/0028-measuring-ad-performance
+- AdAttributionKit for Apple Ads measurement: https://ads.apple.com/app-store/help/attribution/0093-adattributionkit-to-measure-performance
+- Reporting definitions: https://ads.apple.com/app-store/help/reporting/0023-reporting-options-and-definitions
+
+## Apple Developer Documentation
+
+- Custom Product Pages: https://developer.apple.com/app-store/custom-product-pages/
+- App Store ad attribution / AdAttributionKit overview: https://developer.apple.com/app-store/ad-attribution/
+- Apple Ads developer documentation: https://developer.apple.com/documentation/apple_ads
+- Apple Search Ads Campaign Management API 5: https://developer.apple.com/documentation/apple_ads/apple-search-ads-campaign-management-api-5
+
+## Supporting Apple Platform Docs
+
+- ATT overview: https://support.apple.com/en-us/102420
+- Personalized ads on iPhone: https://support.apple.com/guide/iphone/control-how-apple-delivers-advertising-to-you-iphf60a6a256/ios
+
+## Notes
+
+- Prefer the Apple Ads help center and Apple developer docs over blog posts when
+  checking feature availability, measurement behavior, and API capabilities.
+- Re-check placement availability and rollout notes before modeling inventory;
+  Apple changes the App Store ads surface gradually by market.