Keysearch

Build me a focused keyword research, backlinks and rank tracking workflow for the personal core of Keysearch. Requirements:

- Use Python 3.12, FastAPI, PostgreSQL, Playwright, and a small React frontend. Model sites, crawl pages, keyword snapshots, audit findings, and report dates; keep stable source IDs and timestamps.
- Paid product context: Organize keyword research and low-volume rankings from a compliant data API. Build only this DIY scope: Track a user-supplied keyword set, collect low-volume ranking snapshots from a compliant data API, and show trends without pretending to recreate a commercial web index.
- Create projects with domains, keywords, target country, language, device, and tags.
- Fetch rankings only through the configured compliant API and enforce a daily budget.
- Store raw result snapshots and normalized positions so every chart is auditable. Import backlink and keyword files from third-party tools without claiming independent coverage. Add scheduled runs, failure alerts, CSV export, retention settings, and database backups.
- Use a local web page with input, progress, review, and export views. Required input or access: self-hosted server; approved search-data API or manual imports.
- Recovery: Add scheduled runs, failure alerts, CSV export, retention settings, and database backups.
- Acceptance: with one labelled sample, show the input, saved intermediate state, and exported result; verify this invariant: A failed crawl retains its last dated snapshot; a report must not imply backlink or keyword coverage the input lacks.
- Out of scope: keyword database, competitive metrics, backlink data, and affordable bundled workflow; planet-scale crawl index. Keep this a personal, inspectable workflow.
- Include a README with setup, a sample input, required keys or permissions, data location, and the supported scope.

# AGENTS.md — Build guide for Keysearch

## Project scope
Track a user-supplied keyword set, collect low-volume ranking snapshots from a compliant data API, and show trends without pretending to recreate a commercial web index.

Catalogue verdict: no. A consolation build is possible, but the paid product's decisive value sits outside a solo rebuild. For Keysearch, organize keyword research and low-volume rankings from a compliant data API. The hard boundary is keyword database, competitive metrics, backlink data, and affordable bundled workflow, plus proprietary web index and data acquisition.
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
- self-hosted server
- PostgreSQL
- approved search-data API or manual imports
- scheduled worker

## Stack and architecture
- Use Python 3.12, FastAPI, PostgreSQL, Playwright, and a small React frontend.
- Model sites, crawl pages, keyword snapshots, audit findings, and report dates; keep stable source IDs and timestamps.
- Interface for this keyword research, backlinks and rank tracking workflow: a local web page with input, progress, review, and export views.

## Security and data integrity
- Add scheduled runs, failure alerts, CSV export, retention settings, and database backups.
- Validate imported records and file paths; keep user data within the storage location named in the prompt.
- State the practical limit: keyword database, competitive metrics, backlink data, and affordable bundled workflow.

## Agent implementation rules
- Project rule, data: Model sites, crawl pages, keyword snapshots, audit findings, and report dates; keep stable source IDs and timestamps.
- Project rule, behavior: Create projects with domains, keywords, target country, language, device, and tags.
- Project rule, recovery: Add scheduled runs, failure alerts, CSV export, retention settings, and database backups.

## 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 keyword research, backlinks and rank tracking operation with sample or user-owned data: Create projects with domains, keywords, target country, language, device, and tags.
- Show a concrete result or export: Add scheduled runs, failure alerts, CSV export, retention settings, and database backups.
- State the practical limit: keyword database, competitive metrics, backlink data, and affordable bundled workflow.

## Engineering roadmap
1. Phase 1, architecture and data: Use Python 3.12, FastAPI, PostgreSQL, Playwright, and a small React frontend. Model sites, crawl pages, keyword snapshots, audit findings, and report dates; keep stable source IDs and timestamps.
2. Phase 2, implement: Create projects with domains, keywords, target country, language, device, and tags.
3. Phase 3, implement: Fetch rankings only through the configured compliant API and enforce a daily budget.
4. Phase 4, review and output: Store raw result snapshots and normalized positions so every chart is auditable. Add scheduled runs, failure alerts, CSV export, retention settings, and database backups.
5. Phase 5, recovery and acceptance: Add scheduled runs, failure alerts, CSV export, retention settings, and database backups. Verify this invariant with a saved fixture: A failed crawl retains its last dated snapshot; a report must not imply backlink or keyword coverage the input lacks. State the practical limit: keyword database, competitive metrics, backlink data, and affordable bundled workflow.

## Paid-product capabilities outside this build
- keyword database, competitive metrics, backlink data, and affordable bundled workflow
- planet-scale crawl index
- backlink graph
- clickstream estimates
- high-volume location-specific SERPs

## Implementation prompt
Build me a focused keyword research, backlinks and rank tracking workflow for the personal core of Keysearch. Requirements:

- Use Python 3.12, FastAPI, PostgreSQL, Playwright, and a small React frontend. Model sites, crawl pages, keyword snapshots, audit findings, and report dates; keep stable source IDs and timestamps.
- Paid product context: Organize keyword research and low-volume rankings from a compliant data API. Build only this DIY scope: Track a user-supplied keyword set, collect low-volume ranking snapshots from a compliant data API, and show trends without pretending to recreate a commercial web index.
- Create projects with domains, keywords, target country, language, device, and tags.
- Fetch rankings only through the configured compliant API and enforce a daily budget.
- Store raw result snapshots and normalized positions so every chart is auditable. Import backlink and keyword files from third-party tools without claiming independent coverage. Add scheduled runs, failure alerts, CSV export, retention settings, and database backups.
- Use a local web page with input, progress, review, and export views. Required input or access: self-hosted server; approved search-data API or manual imports.
- Recovery: Add scheduled runs, failure alerts, CSV export, retention settings, and database backups.
- Acceptance: with one labelled sample, show the input, saved intermediate state, and exported result; verify this invariant: A failed crawl retains its last dated snapshot; a report must not imply backlink or keyword coverage the input lacks.
- Out of scope: keyword database, competitive metrics, backlink data, and affordable bundled workflow; planet-scale crawl index. Keep this a personal, inspectable workflow.
- Include a README with setup, a sample input, required keys or permissions, data location, and the supported scope.

## 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.