# AGENTS.md — Build guide for Linktree Pro

## Project scope
Edit an ordered list of public links, preview a mobile profile and publish a revision with optional aggregate click totals.

Catalogue verdict: yes. A static page. The most obviously one-shottable thing on this list.
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
- Runtime and tools: Node, Express, better-sqlite3 and server-rendered HTML with a small vanilla-JavaScript editor.
- Before starting: A Node runtime, administrator credentials, writable profile/avatar storage and an HTTPS host; no static-build-only deployment.

## Stack and architecture
- Node, Express, better-sqlite3 and server-rendered HTML with a small vanilla-JavaScript editor
- Data design: Store Profile, Link, Visibility, SortPosition and DailyCount; redirect endpoints resolve only stored active destinations and do not accept arbitrary destination URLs.
- Setup: A Node runtime, administrator credentials, writable profile/avatar storage and an HTTPS host; no static-build-only deployment

## Security and data integrity
- Protect the editor with authentication and CSRF checks. Escape labels and redirect only to stored active HTTPS destinations; counters may fail without breaking the redirect.
- Permit only reviewed HTTPS destinations. Aggregate clicks are not unique people; do not collect identity or promise bot-free analytics from a counter.
- Keep secrets outside client bundles and exported projects; document what leaves the device and make retention/deletion controls visible.

## Agent implementation rules
- Project rule — domain: Store Profile, Link, Visibility, SortPosition and DailyCount; redirect endpoints resolve only stored active destinations and do not accept arbitrary destination URLs.
- Project rule — scope and recovery: Permit only reviewed HTTPS destinations. Aggregate clicks are not unique people; do not collect identity or promise bot-free analytics from a counter.
- Project rule — acceptance: Hide and reorder links, reload and request a hidden link's redirect; published order persists and the hidden destination is not followed or counted.
- Project rule — delivery: document real setup commands and permissions; do not claim a build, accuracy level, performance result or security certification that has not been demonstrated.

## Optional agent skills and references
- Recommended skill: [frontend-design](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md) — compose the proposed responsive site sections with deliberate typography, spacing and honest content. Follow the maintainer's installation instructions and match its requirements to the chosen runtime.
- Recommended skill: [seo-audit](https://github.com/coreyhaines31/marketingskills/blob/main/skills/seo-audit/SKILL.md) — review crawlability, metadata and evidence-based on-page findings without promising search rankings. Follow the maintainer's installation instructions and match its requirements to the chosen runtime.

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 working slice using synthetic or explicitly authorized non-sensitive examples: Edit an ordered list of public links, preview a mobile profile and publish a revision with optional aggregate click totals.
- Share a synthetic example export and the acceptance walkthrough; keep real customer, health, financial and source data private: Hide and reorder links, reload and request a hidden link's redirect; published order persists and the hidden destination is not followed or counted.
- State the limits before asking someone to replace their existing tool: Permit only reviewed HTTPS destinations. Aggregate clicks are not unique people; do not collect identity or promise bot-free analytics from a counter.

## Engineering roadmap
1. Phase 1 — Pin the working slice and create its example input: Edit an ordered list of public links, preview a mobile profile and publish a revision with optional aggregate click totals. Confirm setup: A Node runtime, administrator credentials, writable profile/avatar storage and an HTTPS host; no static-build-only deployment.
2. Phase 2 — Implement persistence and write-time invariants before decorating the UI: Store Profile, Link, Visibility, SortPosition and DailyCount; redirect endpoints resolve only stored active destinations and do not accept arbitrary destination URLs.
3. Phase 3 — Connect the working view to real saved state. Protect the editor with authentication and CSRF checks. Escape labels and redirect only to stored active HTTPS destinations; counters may fail without breaking the redirect.
4. Phase 4 — Expose the app-specific limits and recovery path in context: Permit only reviewed HTTPS destinations. Aggregate clicks are not unique people; do not collect identity or promise bot-free analytics from a counter.
5. Phase 5 — Walk through this concrete acceptance case and preserve its exported evidence: Hide and reorder links, reload and request a hidden link's redirect; published order persists and the hidden destination is not followed or counted. Finish the README and backup/restore instructions; report unfinished capabilities explicitly.

## Paid-product capabilities outside this build
- the drag-and-drop editor
- their analytics dashboard
- hosted-for-you convenience
- integrations you probably weren't using

## Implementation prompt
Build me a self-hosted link page for one creator like Linktree Pro. Requirements:

- Use Node.js, Express, better-sqlite3, and server-rendered HTML with a small vanilla-JavaScript editor. Store one profile, ordered links, a theme object, and daily click counts in ./data/links.db.
- Expose a public profile at / and a protected editor at /admin with credentials from .env and CSRF protection. Edit display name, bio, avatar, link label, destination, visibility, and order. Provide move-up/down buttons as well as pointer reordering.
- Validate destinations as https URLs and escape all labels. The editor shows a mobile-width preview. Theme controls adjust background, foreground, accent, and button shape, with a contrast warning when text becomes hard to read.
- Route clicks through /r/:linkId, look up the configured active destination, increment a daily aggregate counter, and issue a 302 redirect. Never accept an arbitrary destination in query parameters. A disabled or deleted link returns a useful 404 instead of redirecting elsewhere.
- Count redirect requests as clicks and label that bots and previews can inflate them. Store no IP addresses, fingerprints, or raw referrers. If counters fail, the redirect still works; serving the link is more important than collecting analytics.
- Accept bounded image uploads, decode and resize them with Sharp, and discard metadata. Store generated filenames under ./data/avatars, never arbitrary client paths. Provide profile/link JSON export and import with a preview.
- Use plain external links for video, music, bookings, and payments. No embedded third-party scripts, newsletter integration, or checkout processing in this first version. No visitor accounts or telemetry.
- Acceptance: reorder and hide links, reopen the editor, check mobile and keyboard use, redirect one active link, reject an unknown ID, and round-trip a profile export. README covers HTTPS, admin credentials, data backups, and DNS for a custom domain.

EDITORIAL IMPLEMENTATION CONTRACT
Working slice: Edit an ordered list of public links, preview a mobile profile and publish a revision with optional aggregate click totals.
Data and invariants: Store Profile, Link, Visibility, SortPosition and DailyCount; redirect endpoints resolve only stored active destinations and do not accept arbitrary destination URLs.
Boundary and recovery: Permit only reviewed HTTPS destinations. Aggregate clicks are not unique people; do not collect identity or promise bot-free analytics from a counter.
Acceptance walkthrough: Hide and reorder links, reload and request a hidden link's redirect; published order persists and the hidden destination is not followed or counted.
Record actual dependency versions, permissions and provider access in setup instructions. Preserve originals, expose partial failures and document backup/restore. These are acceptance requirements, not a claim of a completed or production-certified build. Add the domain, recovery and acceptance rules to AGENTS.md so future edits preserve them.

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