NicheMaps

Build me a local competitor-app watchlist, the one slice of NicheMaps worth building solo. Requirements:

- Node 22 + TypeScript + SQLite + a tiny localhost UI (Vite + React is fine).
- apps.json lists up to 25 apps with platform (ios|android), store id, and optional advertiser name.
- `npm run refresh` fetches public store listing fields (title, rating, ratings count, free/paid, last updated) via the facundoolano google-play-scraper / app-store-scraper libraries. Respect rate limits; sleep between requests.
- For each app, store deep links to Google Ads Transparency and Meta Ad Library search URLs (domain or advertiser name). Do not pretend you have store-wide ad-running bitmaps.
- Optional: with PLAYWRIGHT=1, open those two URLs headlessly and save a dated HTML snapshot plus a count of creatives mentioning the app name. Expect blocks; document proxy/env needs and fail soft.
- SQLite tables: apps, snapshots, creative_checks. Keep full history.
- Localhost dashboard: table of watched apps, sparkline of ratings-count delta, last creative-check time, and buttons to open the transparency URLs.
- Secrets in .env only (.env.example shipped). No accounts, no cloud, no telemetry.
- Out of scope: crawling the whole store, IAP detection at scale, "apps advertising now" filters, and niche ranking across categories. That dataset is the subscription.
- README: setup, refresh cron example, honest statement that NicheMaps is a proprietary multi-store + ad-library index and this replaces a personal watchlist, not the catalog.

# AGENTS.md — Build guide for NicheMaps

## Project scope
Track a small list of competitor apps, pull public store metadata, open their Google Ads Transparency and Meta Ad Library pages, and note which creatives are still running.

Catalogue verdict: no. You can build a personal watchlist that checks a handful of store listings and ad-library pages, but NicheMaps' value is a continuously refreshed catalog of millions of iOS/Android apps with ad-status, IAP, velocity, and creative evidence you cannot rebuild in one sitting.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- App Store / Play public listing access
- Google Ads Transparency Center
- Meta Ad Library
- SQLite or local JSON storage
- optional residential proxy if scraping at volume

## Stack and architecture
- Node 22 + TypeScript + SQLite + a tiny localhost UI (Vite + React is fine).
- Model data sources, dated observations, derived metrics, and report snapshots; keep stable source IDs and timestamps.
- Interface for this mobile app niche and ad intelligence workflow: a local web page with input, progress, review, and export views.

## Security and data integrity
- `npm run refresh` fetches public store listing fields (title, rating, ratings count, free/paid, last updated) via the facundoolano google-play-scraper / app-store-scraper libraries. Respect rate limits; sleep between requests.
- Validate imported records and file paths; keep user data within the storage location named in the prompt.
- State the practical limit: 5M+ app catalog with searchable filters.

## Agent implementation rules
- Project rule, data: Model data sources, dated observations, derived metrics, and report snapshots; keep stable source IDs and timestamps.
- Project rule, behavior: Optional: with PLAYWRIGHT=1, open those two URLs headlessly and save a dated HTML snapshot plus a count of creatives mentioning the app name. Expect blocks; document proxy/env needs and fail soft.
- Project rule, recovery: `npm run refresh` fetches public store listing fields (title, rating, ratings count, free/paid, last updated) via the facundoolano google-play-scraper / app-store-scraper libraries. Respect rate limits; sleep between requests.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this mobile app niche and ad intelligence operation with sample or user-owned data: Optional: with PLAYWRIGHT=1, open those two URLs headlessly and save a dated HTML snapshot plus a count of creatives mentioning the app name. Expect blocks; document proxy/env needs and fail soft.
- Show a concrete result or export: Localhost dashboard: table of watched apps, sparkline of ratings-count delta, last creative-check time, and buttons to open the transparency URLs.
- State the practical limit: 5M+ app catalog with searchable filters.

## Engineering roadmap
1. Phase 1, architecture and data: Node 22 + TypeScript + SQLite + a tiny localhost UI (Vite + React is fine). Model data sources, dated observations, derived metrics, and report snapshots; keep stable source IDs and timestamps.
2. Phase 2, implement: Optional: with PLAYWRIGHT=1, open those two URLs headlessly and save a dated HTML snapshot plus a count of creatives mentioning the app name. Expect blocks; document proxy/env needs and fail soft.
3. Phase 3, implement: SQLite tables: apps, snapshots, creative_checks. Keep full history.
4. Phase 4, review and output: Localhost dashboard: table of watched apps, sparkline of ratings-count delta, last creative-check time, and buttons to open the transparency URLs.
5. Phase 5, recovery and acceptance: `npm run refresh` fetches public store listing fields (title, rating, ratings count, free/paid, last updated) via the facundoolano google-play-scraper / app-store-scraper libraries. Respect rate limits; sleep between requests. Verify this invariant with a saved fixture: A replayed batch cannot double-count events; missing or late data must be labelled in the report. State the practical limit: 5M+ app catalog with searchable filters.

## Paid-product capabilities outside this build
- 5M+ app catalog with searchable filters
- live ad-running status across the whole store
- IAP and install/rating velocity joins
- aggregated Google and Meta creative history
- working-niche discovery at market scale

## Implementation prompt
Build me a local competitor-app watchlist, the one slice of NicheMaps worth building solo. Requirements:

- Node 22 + TypeScript + SQLite + a tiny localhost UI (Vite + React is fine).
- apps.json lists up to 25 apps with platform (ios|android), store id, and optional advertiser name.
- `npm run refresh` fetches public store listing fields (title, rating, ratings count, free/paid, last updated) via the facundoolano google-play-scraper / app-store-scraper libraries. Respect rate limits; sleep between requests.
- For each app, store deep links to Google Ads Transparency and Meta Ad Library search URLs (domain or advertiser name). Do not pretend you have store-wide ad-running bitmaps.
- Optional: with PLAYWRIGHT=1, open those two URLs headlessly and save a dated HTML snapshot plus a count of creatives mentioning the app name. Expect blocks; document proxy/env needs and fail soft.
- SQLite tables: apps, snapshots, creative_checks. Keep full history.
- Localhost dashboard: table of watched apps, sparkline of ratings-count delta, last creative-check time, and buttons to open the transparency URLs.
- Secrets in .env only (.env.example shipped). No accounts, no cloud, no telemetry.
- Out of scope: crawling the whole store, IAP detection at scale, "apps advertising now" filters, and niche ranking across categories. That dataset is the subscription.
- README: setup, refresh cron example, honest statement that NicheMaps is a proprietary multi-store + ad-library index and this replaces a personal watchlist, not the catalog.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.