update

docs/agent-guide.md

@@ -0,0 +1,15 @@
+# Agent Guide
+
+## Implementation priorities
+
+1. Keep the app simple for a 3-person internal team.
+2. Prefer server-rendered Django flows over heavy frontend complexity.
+3. Optimize for fast item creation and quick search.
+4. Preserve creator attribution on every item.
+5. Treat pricing integrations as advisory.
+
+## Working conventions
+
+- Update the docs whenever a workflow or model meaningfully changes.
+- Keep new fields aligned with the existing thrift-to-sale lifecycle.
+- Add focused tests for item creation, filters, and profit math before expanding the feature set.

docs/architecture.md

@@ -0,0 +1,30 @@
+# Architecture
+
+Arbit is a small internal Django app for tracking thrift acquisitions through resale.
+
+## Goals
+
+- Fast item entry
+- Editable templates for recurring item types
+- Searchable inventory with practical filters
+- Profit tracking and resale pricing guidance
+- Simple per-item attribution to the user who created the item
+
+## Stack
+
+- Django for server-rendered forms, auth, and admin
+- SQLite for local development, PostgreSQL for production
+- HTMX later if the team wants faster inline editing without a full SPA
+
+## Components
+
+- `inventory` app for domain models and dashboard views
+- Django auth for login/logout
+- Django admin for internal management and emergency data editing
+- Templates for the main dashboard and item forms
+
+## Phase 1 Boundaries
+
+- No role-based permissions beyond standard authenticated access
+- No marketplace posting automation
+- Pricing suggestions are advisory and can be overridden manually

docs/domain-model.md

@@ -0,0 +1,22 @@
+# Domain Model
+
+## Core entities
+
+- ItemTemplate: reusable defaults for common purchase types
+- Item: individual acquired object being tracked for resale
+- PriceEstimate: a resale suggestion from comps or manual input
+- ItemNote: internal notes and condition updates
+- ItemPhoto: images attached to the item
+
+## Item lifecycle
+
+1. Created from a template or from scratch
+2. Marked in stock
+3. Optionally listed
+4. Sold or removed from inventory
+
+## Tracking rules
+
+- The creator of the item is stored on the record and shown in item views
+- Profit is based on sold price minus purchase price, fees, and shipping cost
+- Estimated resale price is only a suggestion until sold data exists

docs/implementation-checklist.md

@@ -0,0 +1,24 @@
+# Implementation Checklist
+
+## Phase 1
+
+- [x] Scaffold Django project and auth wiring
+- [x] Create core inventory models
+- [x] Add template-driven item entry
+- [x] Add a searchable dashboard view
+- [x] Add starter tests for profit math and template defaults
+
+## Phase 2
+
+- [ ] Add editable item detail pages
+- [ ] Add sold-price and fee entry workflows
+- [ ] Add photo upload handling
+- [ ] Add price estimate service integration
+- [ ] Add richer search filters and saved views
+
+## Phase 3
+
+- [ ] Add summary charts for profit and inventory velocity
+- [ ] Add bulk updates for item status and pricing
+- [ ] Add local notes history and item activity timeline
+- [ ] Add deployment configuration for PostgreSQL and media storage

docs/pricing.md

@@ -0,0 +1,14 @@
+# Pricing
+
+Pricing recommendations should be advisory, not blocking.
+
+## Rules
+
+- Prefer recently sold listings over active listing prices
+- Store the source and retrieval time for every estimate
+- Keep manual overrides available for every item
+- Fall back to the last known local estimate if the external source fails
+
+## Later integration
+
+The first implementation can use a service wrapper for eBay sold comps or another source without coupling the rest of the app to a single marketplace.

docs/workflows.md

@@ -0,0 +1,19 @@
+# Workflows
+
+## Add item
+
+1. Choose a template or start from scratch.
+2. Fill in item properties.
+3. Save the item and keep the creator attribution.
+
+## Update pricing
+
+1. Pull recent sold comps from an external marketplace source when available.
+2. Store the estimate with a source and timestamp.
+3. Allow manual override when comps are stale or unavailable.
+
+## Sell item
+
+1. Set the sold price.
+2. Mark the item sold.
+3. Use the stored costs to show profit and margin.