Add idea: self-hosted Groktocrawl as AI agent browsing layer

Reviewed-on: #1

README.md

@@ -1,20 +1,101 @@
-# AI Business Ideas
+# AI Business Ideas — Capture & Curation Repository
 
-## How to add an idea
+> **Purpose:** A zero-friction capture layer for AI/agentic business ideas. Every idea is walked through a structured template with the AI assistant. **All sections must have meaningful content** (no empty placeholders), but ideas can be saved at any valid state — `initial`, `in progress`, or `ready for review`. A live sitemap tracks all ideas and their status.
 
-1. Propose a new idea title.
-2. The AI agent will run a structured intake using `TEMPLATE.md`.
-3. The agent must complete the template before anything is added to this repo.
-4. Once complete, the idea is committed as its own subdirectory here, e.g. `ideas/<idea-name>/IDEA.md`.
+---
 
-## Rule
+## 🤖 AI Agent Instructions: How to Walk a User Through a New Idea
 
-Do not skip sections, abbreviate fields, or add ideas without a full template record.
+When a user says **"capture a new idea"** or **"add idea"**, you (the AI) **MUST** follow this exact flow. Do not skip steps. Do not save until the user confirms every section has content.
 
-## Ideas
+### Phase 1 — Initialize
+1. Ask the user for a **slug** (kebab-case folder name, e.g., `ai-first-ebay-cataloging-assistant`).
+2. Create the folder: `ideas/<slug>/`
+3. Copy `TEMPLATE.md` → `ideas/<slug>/README.md` as the working draft.
 
-| Directory | One-Liner | State |
-| --- | --- | --- |
-| *(none yet)* | | |
+### Phase 2 — Guided Capture (One Section at a Time)
+For **each section** in the template, in order:
+1. **Present the section header** and any guidance/examples from the template.
+2. **Prompt the user** for their input. Accept free-form text, bullet points, or rough notes.
+3. **Synthesize & structure** their input into the template format (markdown tables, bullet lists, clear prose).
+4. **Read back the filled section** and ask: *"Does this capture it accurately? Any additions or changes?"*
+5. Only move to the next section when the user **explicitly confirms**.
 
-Update this table whenever a new idea is added.
+**Sections in order:**
+| # | Template Section | Minimum Content Required |
+|---|------------------|--------------------------|
+| 1 | **Title** | Clear, specific, searchable |
+| 2 | **One-Liner** | ≤1 sentence conveying value prop |
+| 3 | **Problem** | Pain point, who experiences it, frequency — all three present |
+| 4 | **Solution** | What it does, core workflows (numbered), MVP scope |
+| 5 | **Target Market** | Primary segment + size indicator (TAM/SAM/SOM or proxy) |
+| 6 | **High-Level Use Cases** | ≥3 concrete, user-facing scenarios |
+| 7 | **High-Level Design / Dependencies** | Architecture overview, external services/APIs, key technical deps |
+| 8 | **Differentiation / Competitive Edge** | Why this vs. alternatives — specific, not generic |
+| 9 | **State of This Idea** | Must be one of: `initial` / `in progress` / `ready for review` |
+| 10 | **Risks** | Technical, Market, Regulatory — at least one bullet each |
+
+### Phase 3 — Finalize & Save
+1. **Validate:** Every section has meaningful content (no "TBD", "—", or empty bullets).
+2. Write the completed `README.md` to `ideas/<slug>/README.md`.
+3. **Update the Sitemap below** (add/update row in the table).
+4. Confirm to the user: *"Idea saved at `ideas/<slug>/README.md` with state `<state>` and sitemap updated."*
+
+> **Save gate:** All 10 sections populated → save allowed at any valid state. No section left blank.
+
+---
+
+## 🗺️ Sitemap — All Ideas & Status
+
+> **Auto-maintained:** The AI updates this table every time an idea is added, modified, or archived.
+
+| Idea (Folder) | Title | One-Liner | State | Last Updated |
+|---------------|-------|-----------|-------|--------------|
+| `ai-first-ebay-cataloging-assistant` | AI-First eBay Photo Listing Assistant | A mobile-first AI assistant that turns smartphone photos of any item (especially industrial or hard-to-identify SKUs) into complete, priced, categorized eBay listings and publishes them directly via the eBay API — while strictly avoiding guesses and using deterministic systems wherever possible. | `in progress` | 2026-06-18 |
+
+---
+
+## 📁 Repository Structure
+
+```
+ai-business-ideas/
+├── README.md              ← This file (AI instructions + sitemap)
+├── TEMPLATE.md            ← Master template (source of truth for structure)
+└── ideas/
+    └── <slug>/            ← One folder per idea
+        └── README.md      ← Populated template for that idea (shown at folder root)
+```
+
+> **Note on file naming:** Inside each idea folder, the file is named `README.md` (not `IDEA.md`). This allows the idea content to appear directly when viewing the folder on Gitea without an extra click.
+
+---
+
+## 📋 Template Reference
+
+See [`TEMPLATE.md`](TEMPLATE.md) for the full section definitions, examples, and formatting expectations. The AI uses this as the canon during guided capture.
+
+---
+
+## 🔧 Maintenance Notes
+
+- **Adding an idea:** Follow the AI instructions above — the AI handles folder creation, guided capture, validation, and sitemap update.
+- **Editing an idea:** The AI re-runs guided capture for only the sections you want to change, then updates `README.md` and the sitemap `Last Updated` column.
+- **State transitions:** Change `State of This Idea` between `initial` → `in progress` → `ready for review` as work progresses. The sitemap `State` column reflects the current value.
+- **Archiving:** Change state to `archived` (not in template but supported) — the sitemap row stays, status reflects it.
+- **Sitemap sync:** If the sitemap ever drifts, the AI can regenerate it by scanning all `ideas/*/README.md` files and reading their `State of This Idea` and top metadata.
+
+---
+
+## ✅ Quality Bar for Saving
+
+An idea is **saved** when:
+- ✅ Every one of the 10 template sections has meaningful content (no placeholder text like "TBD" or "—").
+- ✅ The user has explicitly confirmed each section during the guided walkthrough.
+- ✅ `State of This Idea` is set to a valid value: `initial` \| `in progress` \| `ready for review`.
+- ✅ The sitemap row is added/updated in this README.
+
+> **No empty sections.** Rough notes are fine. Blank sections are not. The guided walkthrough *is* the quality filter.
+
+---
+
+*Generated and maintained by the Hermes AI agent per the instructions above.*

ideas/ai-first-ebay-cataloging-assistant/IDEA.md

@@ -1,69 +0,0 @@
-# AI-first eBay Cataloging Assistant
-
-## One-Liner
-
-An AI-powered assistant that turns raw product descriptions or photos into complete, buyer-ready eBay listings.
-
-## Problem
-
-- **Pain point**: Sellers spend significant time researching comparable sold listings, rewriting descriptions into concise paragraphs, selecting attributes, and choosing keywords that balance appeal with policy compliance.
-- **Who experiences it**: Home resellers, shop owners migrating from in-person sales to eBay, and anyone managing a high volume of SKUs.
-- **How painful / frequent**: This is a repeated, time-consuming task that happens for every new or refreshed listing.
-
-## Solution
-
-- **What does it do**: Accepts free-form notes or images, queries and analyzes the market, and outputs formatted eBay listings optimized for discovery and conversion.
-- **Core workflows**:
-  1. Input raw product notes or photos via chat, email, or Shopify-style CSV.
-  2. Research sold and active comps to suggest pricing.
-  3. Generate titles, descriptions, bullet points, item specifics, and keywords.
-  4. Summarize risk factors (too generic, keyword stuffing, suspicious attribute combinations).
-  5. Prepare the listing for review / export.
-- **Minimum Viable Version**:
-  - Text input only.
-  - Research Web + select data sources (eBay sold data or seller guides).
-  - Structured output + copy-ready formatting.
-  - Simple approval workflow.
-
-## Target Market
-
-- **Primary customer segment**: Casual and power eBay resellers.
-- **Market size indicator**: eBay remains one of the largest global marketplaces; resale and small-business growth continue expanding the addressable seller base.
-
-## High Level Use Cases
-
-- Turn a 2-line WhatsApp note into a listing.
-- Bulk-rewrite existing Shopify/Amazon titles into eBay-optimized listings.
-- Suggest realistic prices using sold-listing benchmarks.
-- Enforce listing quality before publish.
-
-## High Level Design / Dependencies
-
-- **Architecture / system design overview**:
-  - Web app + mobile-friendly chat interface.
-  - Multiple research tools in parallel.
-  - Template engine for listing content.
-  - Approval queue with export (eBay file format, JSON, CSV).
-- **External services, data sources, APIs**:
-  - Google Shopping or eBay integration for research.
-  - eBay API for direct publish (later phase).
-  - Vision model for photo descriptions.
-- **Key technical dependencies**:
-  - Hermes agents or equivalent orchestration.
-  - Structured templates + rules for eBay listing quality.
-
-## Differentiation / Competitive Edge
-
-- Chat-native seller workflow (as natural as texting a listing to an assistant) rather than rigid spreadsheets.
-- Compliance-focused generation that avoids policy pitfalls before a human reviewer sees them.
-- Easy integration with product data already captured in other tools or raw notes.
-
-## State of this idea
-
-- `initial`
-
-## Risks
-
-- **Technical**: Compiling reliable, current comparable pricing at scale.
-- **Market**: Seller expectations around publication automation vs. human judgment.
-- **Regulatory**: eBay policy compliance for listing content; data-source licensing.

ideas/ai-first-ebay-cataloging-assistant/README.md

@@ -0,0 +1,105 @@
+# AI-First eBay Photo Listing Assistant
+
+## One-Liner
+
+A mobile-first AI assistant that turns smartphone photos of any item (especially industrial or hard-to-identify SKUs) into complete, priced, categorized eBay listings and publishes them directly via the eBay API — while strictly avoiding guesses and using deterministic systems wherever possible.
+
+## Problem
+
+- **Pain point**: Sellers waste significant time identifying industrial/vintage/unknown items, determining correct categories and item specifics, researching fair market prices from sold listings, and formatting compliant listings. Poor identification or pricing leads to low visibility or lost margin.
+- **Who experiences it**: Power resellers, warehouse liquidators, estate sellers, and anyone managing high volumes of non-standard or "mystery" inventory.
+- **How painful / frequent**: Every unique SKU requires manual research. Mis-categorization kills discoverability. Wrong pricing = no sales or leaving money on the table. This happens per item at scale.
+
+## Solution
+
+- **What it does**: Accepts smartphone photos (including multi-item frames), identifies items without guessing, recommends pricing based on recent sold listings (with active listing comparison), factors in realistic shipping, applies the user’s eBay Seller Templates, and publishes directly to eBay via OAuth. Supports both on-the-go mobile capture and later desktop bulk review.
+
+- **Core workflows**:
+  1. Capture photos on phone (single items or bulk "shelf dump").
+  2. System segments multiple items when present.
+  3. Vision model attempts identification; if confidence is low or photos are unsuitable for advertising, it prompts the user for better/different shots rather than guessing.
+  4. Collects contextual data (location like "Rack 2 Shelf A", condition notes) and makes smart assumptions where possible (e.g., sealed box = New; open shelf stock = NOS with minor dust/patina).
+  5. Pricing engine queries sold listings first, shows distribution and trend, then compares against active listings and recommends shipping methods based on comparable sales.
+  6. Applies the user’s existing eBay Seller Templates for policies and defaults.
+  7. Detects potential duplicates against existing active listings and asks whether this is a net-new item or a quantity increase.
+  8. Generates title, description, item specifics, and keywords.
+  9. User reviews on mobile or desktop, then publishes directly via eBay API.
+
+- **Minimum Viable Version**:
+  - Photo capture and identification with "ask for better photos" guardrails.
+  - Sold-price based pricing recommendations + active listing comparison.
+  - Basic eBay OAuth connection and direct publish.
+  - Support for eBay Seller Templates.
+  - Duplicate detection and inventory reconciliation prompt.
+  - Responsive web app (PWA) usable on both mobile and desktop.
+
+## Target Market
+
+- **Primary customer segment**: Power eBay resellers (500+ listings/year) who regularly deal with industrial parts, MRO, auto, electronics, vintage, or liquidation inventory where items are not easily identifiable by SKU or barcode.
+- **Market size indicator**: eBay remains one of the largest global marketplaces with a large and growing base of professional resellers. The industrial/MRO/liquidation segment is underserved by existing listing tools that assume known products.
+
+## High-Level Use Cases
+
+- Warehouse worker photographs a bin of unknown industrial parts → system segments items, identifies with high confidence or requests better photos, suggests pricing from sold comps, and queues for desktop review.
+- Estate liquidator takes photos of vintage test equipment on-site → later reviews and publishes from desktop with location metadata preserved.
+- Bulk "photo dump" workflow: seller takes dozens of photos in the warehouse, then processes the batch at their desk with full pricing, template, and duplicate-checking support.
+- System detects a near-identical item already listed and asks: "Is this new stock or a quantity bump on the existing listing?"
+
+## High-Level Design / Dependencies
+
+- **Architecture / system design overview**:
+  - Responsive web app (PWA) — mobile-first capture + full-featured desktop review.
+  - Backend API handling photo processing, pricing engine, and eBay integration.
+  - **Core design principle**: Maximize deterministic systems. As much functionality as possible (pricing lookups, shipping recommendations, template application, duplicate detection, inventory reconciliation, eBay API interactions) must be rule-based and deterministic. AI is deliberately constrained to narrow, well-scoped tasks only (primarily vision-based identification and photo quality assessment) to minimize hallucinations and incorrect outputs.
+
+- **External services, data sources, APIs**:
+  - eBay OAuth + Sell APIs (Inventory, Fulfillment) for direct publishing and listing reconciliation.
+  - eBay Browse API for sold and active listing data.
+  - Vision models (GPT-4o / Claude 3.5 / Gemini) used only for identification and photo quality assessment, with strict "do not guess" rules.
+  - Pricing data sources (eBay sold data primary; Keepa/Google Shopping as fallback).
+
+- **Key technical dependencies**:
+  - Secure per-user token storage and refresh handling.
+  - Job queue for background processing of bulk uploads.
+  - Structured templates and rules engine to constrain AI output.
+
+## Differentiation / Competitive Edge
+
+- **Photo-first for unknown items** — works when there is no SKU or barcode, unlike most existing tools.
+- **"Never guesses" discipline** — system requests better photos rather than hallucinating identification or condition.
+- **Sold-price grounded pricing** with transparent comparison to active listings and realistic shipping recommendations.
+- **Leverages eBay’s own Seller Templates** instead of building a competing template system.
+- **Inventory-aware** — detects duplicates and helps maintain accurate quantities.
+- **Hybrid mobile + desktop workflow** designed for real-world bulk capture scenarios.
+
+## Revenue Model (Plan of Record)
+
+**Model Type:** Tiered subscription (Free / Bronze / Silver / Gold) with dual monthly usage caps.
+
+**Core Principle:** Charge when the AI performs the heaviest work — initial cataloging and draft creation.
+
+**Two-Cap Structure (per tier):**
+- **Early ID / Pre-processing** (higher cap): Segmentation, identification, and initial analysis of uploaded photos. This produces a superset of what the user ultimately decides to list.
+- **Draft Submissions** (lower cap): Actual creation of structured, priced drafts. This is the primary billable event.
+
+**Key Rules:**
+- Publishing a draft to eBay is free.
+- Any edits to previously created drafts are free.
+- All plans require email validation to reduce multi-account abuse.
+- Bulk export of clean structured data is restricted or degraded for non-published drafts (anti-gaming control).
+- Tier positioning will align with eBay’s Store subscription levels (Starter/Basic/Premium/Anchor) for natural customer segmentation.
+
+**Pricing:** Final numbers and exact allowances are TBD pending COGS analysis (primarily vision model inference costs). The model will use blocks of draft submissions within subscription tiers rather than pure usage-based or unlimited top-tier plans.
+
+This is the current Plan of Record.
+
+## State of This Idea
+
+`in progress`
+
+## Risks
+
+- **Technical**: Vision model accuracy on obscure industrial parts; maintaining fresh, reliable sold-price data at scale; eBay API rate limits and policy compliance.
+- **Market**: Seller trust in AI-generated pricing and descriptions; competition from eBay’s own future AI tools.
+- **Regulatory**: eBay API terms of service and automation policies; data privacy considerations when storing user photos and inventory data.
+- **Business Model**: Risk of users extracting research value without triggering draft submissions; managing the gap between pre-processing and actual submissions without creating poor user experience.

ideas/self-hosted-groktocrawl-browsing-layer.md

@@ -0,0 +1,46 @@
+# Self-Hosted Groktocrawl as AI Agent Browsing Layer
+
+**Date:** 2026-07-10  
+**Source:** https://github.com/groktopus/groktocrawl  
+**Status:** Idea  
+**Category:** Infrastructure / Agent Optimization
+
+## Core Idea
+
+Replace or supplement the current browser/web browsing tools with a self-hosted Groktocrawl instance as the AI agent browsing layer for this Hermes setup.
+
+## What is Groktocrawl?
+
+Self-hosted Firecrawl alternative with:
+- Full Firecrawl v2 API compatibility (scrape, search, crawl, extract, browser sessions)
+- Built-in semantic search (Qdrant vector index)
+- Grounded Q&A with citations
+- Autonomous research agent endpoint (`/v2/agent`)
+- Site adapters (GitHub, Substack, Reddit, YouTube, Bluesky, etc.)
+- Smart scrape cache with ETag/Last-Modified revalidation
+- Three-tier scraping: llms.txt → markdown accept → Playwright render
+- Content quality scoring
+- MCP server integration
+- One `docker compose up` deployment
+- MIT licensed
+
+## Why this matters
+
+1. **Cost** — self-hosted, no Firecrawl API costs. Already have GPU infra and Docker.
+2. **Quality** — cleaner input for agents (smart scraping, quality scoring, llms.txt-first)
+3. **Semantic layer** — built-in vector search over scraped content
+4. **Agent-native** — grounded Q&A agent for multi-hop research without chaining 5 tools
+5. **MCP integration** — agents connect directly as a tool
+6. **Site adapters** — structured extraction without writing custom scrapers
+7. **Cache** — reduces redundant scraping
+
+## Target deployment
+
+Either this Hermes planner instance (TyUBUMini) or the VPS. Docker compose, minimal overhead.
+
+## Next steps (if pursuing)
+
+- Test deploy on VPS alongside existing services
+- Point Hermes MCP at the Groktocrawl endpoint
+- Compare browse quality vs current web_extract/browser tools
+- Evaluate if the research agent endpoint replaces need for separate browsing + extraction