130 lines
5.1 KiB
Markdown
130 lines
5.1 KiB
Markdown
# VeriPath
|
|
|
|
A human-supervised verification service for local businesses. We prevent silent customer loss by ensuring customers can find, trust, and engage a business, and that search engines and AI systems can find, understand, and accurately represent it.
|
|
|
|
This repository defines the audit methodology, evidence standards, canonical business record schema, client records, and operational workflow for VeriPath.
|
|
|
|
---
|
|
|
|
## Current Focus (read this first)
|
|
|
|
| Horizon | What it is | Status |
|
|
|---------|------------|--------|
|
|
| **NOW — Operating mode** | Manual audits: evidence capture, AI representation testing, Silent Customer Loss Maps, canonical business records, owner review | **Active** |
|
|
| **LATER — Deferred** | GeoLocal integration, MCP/agent infrastructure, payment flows, automated multi-tenant platforms | **Deferred** |
|
|
|
|
**Operating truth:** this README, evidence standards, canonical record schema, audit methodology, and client records.
|
|
|
|
If a deferred item conflicts with current operating docs, the operating docs win until explicitly promoted with a dated decision.
|
|
|
|
---
|
|
|
|
## Working Definition
|
|
|
|
> We continuously prevent silent customer loss for local businesses by making sure customers can find, trust, and engage the business, and that search engines and AI systems can find, understand, and accurately represent it, often before the business would notice something was wrong.
|
|
|
|
---
|
|
|
|
## Core Concepts
|
|
|
|
### Silent Customer Loss
|
|
|
|
Silent Customer Loss is the umbrella term for customer acquisition problems that occur without the business owner clearly seeing the loss.
|
|
|
|
It includes:
|
|
- **Customer Path Leakage** — a customer has interest or intent, but digital friction prevents contact, booking, visiting, or engagement.
|
|
- **Discovery Failure** — a potential customer never meaningfully encounters the business because customers, search engines, or AI systems do not find, understand, surface, or accurately represent it.
|
|
|
|
### Service Domains
|
|
|
|
1. **Customer Path Integrity** — customers can find, trust, contact, book, visit, or otherwise engage without preventable digital friction.
|
|
2. **AI Visibility Integrity / AEO** — search engines and AI systems can find, understand, and accurately represent the business.
|
|
3. **Local Competitive Awareness** — local market context via competitor visibility, positioning, review movement, and AI-answer comparison.
|
|
|
|
### Evidence Model
|
|
|
|
- **Tier 1: Verified** — concrete, timestamped, observable, or instrument-backed findings, confirmed by owner or independent sources.
|
|
- **Tier 2: Corroborated** — confirmed by independent sources.
|
|
- **Tier 3: Indicative** — single source, probabilistic, or directional.
|
|
|
|
Field states:
|
|
- `observed` — captured from a source but not independently confirmed
|
|
- `verified` — confirmed by independent sources or owner approval
|
|
- `stale` — previously accurate but freshness has expired
|
|
- `disputed` — conflicting evidence exists; resolution pending
|
|
|
|
### Operating Rule
|
|
|
|
> Agents may detect and draft. Humans approve before publish.
|
|
|
|
---
|
|
|
|
## Audit Workflow
|
|
|
|
```
|
|
Intake
|
|
→ evidence capture (website, GBP, NAP, schema, listings)
|
|
→ AI representation test (buyer-intent queries across models)
|
|
→ Silent Customer Loss Map
|
|
→ evidence classification (tier + source independence)
|
|
→ draft canonical business record
|
|
→ owner review and confirmation
|
|
→ correction plan
|
|
→ before/after measurement
|
|
```
|
|
|
|
---
|
|
|
|
## Canonical Business Record
|
|
|
|
Schema: `docs/architecture/canonical-business-record-v0.1.1.md`
|
|
Policy: `docs/architecture/evidence-freshness-policy-v0.1.md`
|
|
|
|
VeriPath is the system of record. Downstream consumers (GeoLocal, APIs, MCP tools) treat the canonical record as read-only.
|
|
|
|
---
|
|
|
|
## Decision Records
|
|
|
|
Core philosophy and architectural decisions are recorded in `docs/decisions/`. See the roadmap for the current execution plan.
|
|
|
|
| Decision | Path |
|
|
|----------|------|
|
|
| Scope narrowed: VeriPath first, GeoLocal deferred | `docs/decisions/2026-08-13-narrowing-scope-veripath-first.md` |
|
|
| VeriPath owns canonical truth | `docs/decisions/2026-08-12-veripath-system-of-record-boundary.md` |
|
|
| Execution roadmap v0.1 | `docs/roadmap/execution-roadmap-v0.1.md` |
|
|
|
|
---
|
|
|
|
## Active Client Instances
|
|
|
|
| Client | Status | Path |
|
|
|--------|--------|------|
|
|
| Phoenix Salon + Spa | Active — audit and canonical record | `docs/clients/phoenix-salons/` — data: `client-data-pss` |
|
|
| Overcome Fitness | Draft benchmark | `docs/clients/overcome-fitness/` |
|
|
|
|
---
|
|
|
|
## Repository Structure
|
|
|
|
```
|
|
docs/
|
|
decisions/ # dated decision records
|
|
roadmap/ # execution plan and phases
|
|
architecture/ # schema, evidence policy, agent boundaries
|
|
clients/ # per-client audit records and reports
|
|
operations/ # operational manuals and ledgers
|
|
research/ # competitive and market research
|
|
specifications/ # JSON schemas and data contracts
|
|
implementation/ # automation scripts and tools
|
|
tools/ # operational forms (GBP snapshot, etc.)
|
|
```
|
|
|
|
---
|
|
|
|
## Philosophy
|
|
|
|
Users → Problems → Requirements → Evidence → Records → Automation
|
|
|
|
No automation runs until the manual workflow is proven. No infrastructure is built until the audit produces paid value.
|