KFA Marketplace

Build me a small two-sided marketplace for used mechanical keyboards like KFA Marketplace, for a community I
  already have. Requirements:

- Django + SQLite, server-rendered templates with vanilla JS, no frontend framework, one process.
- Sellers post listings: board name, condition notes, up to 8 photos, a fixed price, and a shipped weight in
  pounds. Single quantity, sold means gone.
- A /moderate queue: new listings stay hidden until I approve them.
- Stripe Checkout for purchase; verify the webhook signature and mark a listing sold only when the payment
  event lands, not on redirect.
- On sale, buy a label through the EasyPost API from the seller's address and the listing weight, then email
  both sides the tracking link.
- A seller ledger: each sale credits the seller's balance minus a fee percentage from .env; a /payouts page
  shows what I owe whom, paid out by hand and recorded manually.
- Stripe and EasyPost keys in .env; Django's built-in auth for buyers and sellers, no telemetry, everything
  on my own server.
- Out of scope: escrow, buyer protection, dispute flows, and inspecting anything. Trust between strangers is
  my problem, not the app's.
- README with setup, stripe listen webhook config for local testing, and the fee math.

# AGENTS.md — Build guide for KFA Marketplace

## Project scope
List used keyboards with photos and condition notes, take Stripe Checkout payments, buy shipping labels for sellers, and track each board from sold to delivered.

Catalogue verdict: no. The software is the vibe-codeable part: listings, cart, Stripe checkout, shipping labels, seller payouts. An agent can stand all of that up in a weekend, and the consolation prompt below does. What it cannot stand up is the market. KFA is a two-sided used-keyboard exchange where every board passes through a warehouse for inspection and PCB testing before the buyer sees it, and the fee pays for that inspection and for the crowd on both sides. A clone launches empty.
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
- Stripe account
- EasyPost account
- public HTTPS deployment
- email provider

## Stack and architecture
- Django + SQLite, server-rendered templates with vanilla JS, no frontend framework, one process.
- Model original assets, edit operations, previews, and exported versions; store source IDs and timestamps for each.
- Interface for this used and aftermarket mechanical keyboards workflow: a local web page with input, progress, review, and export views.

## Security and data integrity
- On invalid input or interrupted processing, keep the original record, show the failed step, and permit a safe retry.
- Keep API keys and OAuth secrets in .env; redact them from logs, generated files, and error responses.
- State the practical limit: liquidity: buyers and sellers who are already there, which is the product.

## Agent implementation rules
- Project rule, data: Model original assets, edit operations, previews, and exported versions; store source IDs and timestamps for each.
- Project rule, behavior: Sellers post listings: board name, condition notes, up to 8 photos, a fixed price, and a shipped weight in pounds. Single quantity, sold means gone.
- Project rule, recovery: On invalid input or interrupted processing, keep the original record, show the failed step, and permit a safe retry.

## 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 used and aftermarket mechanical keyboards operation with sample or user-owned data: Sellers post listings: board name, condition notes, up to 8 photos, a fixed price, and a shipped weight in pounds. Single quantity, sold means gone.
- Show a concrete result or export: A seller ledger: each sale credits the seller's balance minus a fee percentage from .env; a /payouts page shows what I owe whom, paid out by hand and recorded manually.
- State the practical limit: liquidity: buyers and sellers who are already there, which is the product.

## Engineering roadmap
1. Phase 1, architecture and data: Django + SQLite, server-rendered templates with vanilla JS, no frontend framework, one process. Model original assets, edit operations, previews, and exported versions; store source IDs and timestamps for each.
2. Phase 2, implement: Sellers post listings: board name, condition notes, up to 8 photos, a fixed price, and a shipped weight in pounds. Single quantity, sold means gone.
3. Phase 3, implement: A /moderate queue: new listings stay hidden until I approve them.
4. Phase 4, review and output: A seller ledger: each sale credits the seller's balance minus a fee percentage from .env; a /payouts page shows what I owe whom, paid out by hand and recorded manually.
5. Phase 5, recovery and acceptance: On invalid input or interrupted processing, keep the original record, show the failed step, and permit a safe retry. Verify this invariant with a saved fixture: An invalid input or interrupted operation must retain the source and show a recoverable state; exported records must reload with the same IDs. State the practical limit: liquidity: buyers and sellers who are already there, which is the product.

## Paid-product capabilities outside this build
- liquidity: buyers and sellers who are already there, which is the product
- warehouse QC: every board is inspected and its PCB tested before delivery
- buyer protection backed by that inspection instead of a seller's photos
- payout operations: KYC, earnings ledgers, and withdrawal handling
- fraud and dispute handling when a deal goes sideways

## Implementation prompt
Build me a small two-sided marketplace for used mechanical keyboards like KFA Marketplace, for a community I
  already have. Requirements:

- Django + SQLite, server-rendered templates with vanilla JS, no frontend framework, one process.
- Sellers post listings: board name, condition notes, up to 8 photos, a fixed price, and a shipped weight in
  pounds. Single quantity, sold means gone.
- A /moderate queue: new listings stay hidden until I approve them.
- Stripe Checkout for purchase; verify the webhook signature and mark a listing sold only when the payment
  event lands, not on redirect.
- On sale, buy a label through the EasyPost API from the seller's address and the listing weight, then email
  both sides the tracking link.
- A seller ledger: each sale credits the seller's balance minus a fee percentage from .env; a /payouts page
  shows what I owe whom, paid out by hand and recorded manually.
- Stripe and EasyPost keys in .env; Django's built-in auth for buyers and sellers, no telemetry, everything
  on my own server.
- Out of scope: escrow, buyer protection, dispute flows, and inspecting anything. Trust between strangers is
  my problem, not the app's.
- README with setup, stripe listen webhook config for local testing, and the fee math.

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