@reneturcios/shelfsignal 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rene Turcios
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# ShelfSignal
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**The open store index for AI agents.**
+
+Local merchants list what they actually sell. AI agents find real food and real products nearby, score how likely each item is actually in stock, and check a validation receipt before they send a human across town. Merchants pay one flat price to get listed. Nobody takes 30% of their food.
+
+DoorDash and the delivery apps built a closed index: they own the customer, scrape or rent the menu, charge the merchant 15-30% per order, and still cannot tell you whether the kitchen has the thing you want. ShelfSignal is the opposite shape:
+
+- **Merchant-owned listing.** The store submits its own stuff, its own prices, its own stock. The listing belongs to the merchant, not the platform.
+- **Built for agents, not ads.** One MCP server any agent can query: find stores, find items, check stock, validate the listing. No sponsored placement, ever.
+- **Stock is a scored signal, not a claim.** Every item carries a last-confirmed date. The likelihood engine turns that evidence into a 0-100 score with printed reasons, so agents stop bluffing "they have it" and start saying "confirmed today, likely in stock."
+- **Validation receipts.** Every listing carries checks an agent can verify: complete profile, real prices, fresh inventory, declared fulfillment. Tier: VERIFIED, LISTED, STALE, or INCOMPLETE.
+- **Flat money.** $100 Starter Store, one time, listed and validated. No per-order commission. See [docs/PRICING.md](docs/PRICING.md).
+
+## Quick start
+
+```bash
+npm install
+npm run build
+npm test
+
+node dist/cli.js coverage
+node dist/cli.js search "birria" --city "San Francisco"
+node dist/cli.js stock sf-mission-taqueria-demo "Birria tacos"
+node dist/cli.js validate sf-mission-taqueria-demo
+node dist/cli.js mcp        # run the MCP server (stdio)
+```
+
+## MCP tools
+
+| Tool | What it does |
+|---|---|
+| `search_stores` | Find stores by text, city, category, or type |
+| `search_items` | Find a food or product across every listed store |
+| `get_store` | Full listing: hours, address, fulfillment, items, stock |
+| `check_stock` | Stock-likelihood verdict (score, band, reasons) for one item |
+| `validate_store` | Validation receipt and tier for one listing |
+| `submit_store` | Validate a merchant intake and preview its listing + receipt |
+| `list_coverage` | Cities, categories, and store count in the index |
+
+## For merchants
+
+You run a store in the city. For $100 you get listed where the agents look:
+
+1. Fill the intake (10 minutes): who you are, where you are, your hours, and the stuff you sell with real prices. Template: [examples/submission.example.json](examples/submission.example.json), field guide: [docs/INTAKE.md](docs/INTAKE.md).
+2. We validate it and your listing goes live with its first receipt.
+3. Update stock whenever it changes with one command or one message. Fresh listings rank as VERIFIED; stale ones decay honestly instead of lying to customers.
+
+No commission. No tablet on your counter. No competing with your own listing.
+
+## How it works
+
+- The registry is the source of truth: `registry/stores.json` (v0.1, git-backed, every change reviewable).
+- The likelihood engine is deterministic: merchant-reported status, confirmation freshness, staple vs specialty. No model guesses.
+- The management layer is freshness: listings decay, validation re-runs on every read, and merchants see exactly what an agent sees. Roadmap in [docs/MANAGEMENT.md](docs/MANAGEMENT.md).
+- Full design: [docs/SPEC.md](docs/SPEC.md). Why this beats the delivery model: [docs/VS-DOORDASH.md](docs/VS-DOORDASH.md).
+
+Bundled stores are sample data and are flagged `demo: true` in every response. Real merchants are never marked demo, and demo stores are never presented as real.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from "node:fs";
+import { loadRegistry, registryPath, getStore, searchStores, searchItems, listCities, listCategories } from "./registry.js";
+import { stockLikelihood } from "./likelihood.js";
+import { validateStore } from "./validate.js";
+import { processSubmission } from "./submit.js";
+const [cmd, ...args] = process.argv.slice(2);
+const flag = (name) => {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 ? args[i + 1] : undefined;
+};
+const VALUE_FLAGS = new Set(["--city", "--category", "--type", "--query"]);
+const positional = [];
+for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (VALUE_FLAGS.has(a)) {
+        i++;
+        continue;
+    }
+    if (a.startsWith("--"))
+        continue;
+    positional.push(a);
+}
+const out = (data) => console.log(JSON.stringify(data, null, 2));
+function usage() {
+    console.log(`ShelfSignal: the open store index for AI agents
+
+Usage:
+  shelfsignal list [--city <city>] [--category <cat>] [--type <type>] [--query <text>]
+  shelfsignal search <item> [--city <city>]          Find a food or product across stores
+  shelfsignal store <store-id>                        Full listing for one store
+  shelfsignal stock <store-id> <item>                 Stock-likelihood verdict with reasons
+  shelfsignal validate <store-id>                     Validation receipt for a listing
+  shelfsignal validate-all                            Receipts for every listing
+  shelfsignal submit <submission.json> [--write]      Check a merchant intake; --write adds it to the registry
+  shelfsignal coverage                                Cities, categories, store count
+  shelfsignal mcp                                     Run the MCP server (stdio)
+`);
+}
+async function main() {
+    switch (cmd) {
+        case "mcp": {
+            const { runMcp } = await import("./mcp.js");
+            await runMcp();
+            return;
+        }
+        case "list": {
+            out(searchStores(loadRegistry(), { query: flag("query"), city: flag("city"), category: flag("category"), type: flag("type") }));
+            return;
+        }
+        case "search": {
+            const query = positional.join(" ");
+            if (!query)
+                return usage();
+            out(searchItems(loadRegistry(), query, flag("city")).map(({ store, item }) => ({ storeId: store.id, storeName: store.name, item })));
+            return;
+        }
+        case "store": {
+            const store = getStore(loadRegistry(), positional[0] ?? "");
+            out(store ?? { error: `No store with id ${positional[0]}` });
+            return;
+        }
+        case "stock": {
+            const reg = loadRegistry();
+            const store = getStore(reg, positional[0] ?? "");
+            if (!store)
+                return out({ error: `No store with id ${positional[0]}` });
+            const name = positional.slice(1).join(" ");
+            const item = store.items.find((i) => i.name.toLowerCase() === name.toLowerCase())
+                ?? store.items.find((i) => i.name.toLowerCase().includes(name.toLowerCase()));
+            out(item ? stockLikelihood(store, item) : { error: `${store.name} does not list '${name}'`, listedItems: store.items.map((i) => i.name) });
+            return;
+        }
+        case "validate": {
+            const store = getStore(loadRegistry(), positional[0] ?? "");
+            out(store ? validateStore(store) : { error: `No store with id ${positional[0]}` });
+            return;
+        }
+        case "validate-all": {
+            out(loadRegistry().stores.map((s) => validateStore(s)));
+            return;
+        }
+        case "submit": {
+            const file = positional[0];
+            if (!file)
+                return usage();
+            const result = processSubmission(JSON.parse(readFileSync(file, "utf8")));
+            out(result);
+            if (result.ok && args.includes("--write") && result.store) {
+                const path = registryPath();
+                const reg = loadRegistry(path);
+                if (reg.stores.some((s) => s.id === result.store.id)) {
+                    console.error(`Store id ${result.store.id} already exists in the registry; not overwritten.`);
+                    process.exitCode = 1;
+                    return;
+                }
+                reg.stores.push(result.store);
+                writeFileSync(path, JSON.stringify(reg, null, 2) + "\n");
+                console.error(`Wrote ${result.store.id} to ${path}`);
+            }
+            if (!result.ok)
+                process.exitCode = 1;
+            return;
+        }
+        case "coverage": {
+            const reg = loadRegistry();
+            out({ cities: listCities(reg), categories: listCategories(reg), stores: reg.stores.length });
+            return;
+        }
+        default:
+            usage();
+    }
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./registry.js";
+export * from "./likelihood.js";
+export * from "./validate.js";
+export * from "./submit.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./registry.js";
+export * from "./likelihood.js";
+export * from "./validate.js";
+export * from "./submit.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC"}

package/dist/likelihood.d.ts

@@ -0,0 +1,12 @@
+import type { Store, StoreItem, StockVerdict } from "./types.js";
+export declare function daysBetween(fromIso: string, now: Date): number;
+/**
+ * Deterministic stock-likelihood engine.
+ *
+ * An agent should never tell a human "they have it" on a guess. ShelfSignal
+ * scores the *evidence* instead: what the merchant last confirmed, how fresh
+ * that confirmation is, and whether the item is an everyday staple or a
+ * specialty item that sells out. Every verdict ships its reasons so the
+ * calling agent can quote them instead of bluffing.
+ */
+export declare function stockLikelihood(store: Store, item: StoreItem, now?: Date): StockVerdict;

package/dist/likelihood.js

@@ -0,0 +1,82 @@
+export function daysBetween(fromIso, now) {
+    const from = new Date(fromIso + (fromIso.length === 10 ? "T12:00:00Z" : ""));
+    if (Number.isNaN(from.getTime()))
+        return Number.POSITIVE_INFINITY;
+    return Math.max(0, Math.floor((now.getTime() - from.getTime()) / 86_400_000));
+}
+/**
+ * Deterministic stock-likelihood engine.
+ *
+ * An agent should never tell a human "they have it" on a guess. ShelfSignal
+ * scores the *evidence* instead: what the merchant last confirmed, how fresh
+ * that confirmation is, and whether the item is an everyday staple or a
+ * specialty item that sells out. Every verdict ships its reasons so the
+ * calling agent can quote them instead of bluffing.
+ */
+export function stockLikelihood(store, item, now = new Date()) {
+    const reasons = [];
+    let score;
+    switch (item.stock) {
+        case "in_stock":
+            score = 90;
+            reasons.push("Merchant last reported this item in stock");
+            break;
+        case "low":
+            score = 45;
+            reasons.push("Merchant last reported this item running low");
+            break;
+        case "out":
+            score = 5;
+            reasons.push("Merchant last reported this item out of stock");
+            break;
+        default:
+            score = 35;
+            reasons.push("Merchant has not reported a stock status for this item");
+    }
+    const age = daysBetween(item.lastConfirmed, now);
+    if (!Number.isFinite(age)) {
+        score -= 25;
+        reasons.push("No confirmation date on record, freshness unknown");
+    }
+    else if (age === 0) {
+        reasons.push("Confirmed today");
+    }
+    else if (age <= 2) {
+        score -= 5;
+        reasons.push(`Confirmed ${age} day${age === 1 ? "" : "s"} ago`);
+    }
+    else if (age <= 7) {
+        score -= 15;
+        reasons.push(`Confirmed ${age} days ago, getting stale`);
+    }
+    else if (age <= 30) {
+        score -= 30;
+        reasons.push(`Confirmed ${age} days ago, stale signal`);
+    }
+    else {
+        score -= 45;
+        reasons.push(`Last confirmed ${age} days ago, treat as unknown`);
+    }
+    if (item.staple) {
+        score += 5;
+        reasons.push("Everyday staple item, restocked routinely");
+    }
+    if (store.tier === "starter" || store.tier === "growth" || store.tier === "pro") {
+        reasons.push(`Listing tier: ${store.tier}`);
+    }
+    if (store.demo)
+        reasons.push("DEMO listing, sample data only, not a real merchant claim");
+    score = Math.max(0, Math.min(100, Math.round(score)));
+    const band = score >= 75 ? "likely" : score >= 50 ? "probable" : score >= 25 ? "uncertain" : "unlikely";
+    return {
+        storeId: store.id,
+        storeName: store.name,
+        item: item.name,
+        score,
+        band,
+        reasons,
+        lastConfirmed: item.lastConfirmed ?? null,
+        demo: Boolean(store.demo),
+    };
+}
+//# sourceMappingURL=likelihood.js.map

package/dist/likelihood.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"likelihood.js","sourceRoot":"","sources":["../src/likelihood.ts"],"names":[],"mappings":"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"}

package/dist/mcp.d.ts

@@ -0,0 +1 @@
+export declare function runMcp(): Promise<void>;

package/dist/mcp.js

@@ -0,0 +1,51 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { loadRegistry, getStore, searchStores, searchItems, listCities, listCategories } from "./registry.js";
+import { stockLikelihood } from "./likelihood.js";
+import { validateStore } from "./validate.js";
+import { processSubmission } from "./submit.js";
+const text = (data) => ({ content: [{ type: "text", text: JSON.stringify(data, null, 2) }] });
+export async function runMcp() {
+    const server = new McpServer({ name: "shelfsignal", version: "0.1.0" });
+    server.tool("search_stores", "Find real local stores (restaurants, groceries, bakeries, bodegas, markets) in a city. Returns merchant-submitted listings, not scraped delivery-app menus.", {
+        query: z.string().optional().describe("Free text matched against store names, categories, and items."),
+        city: z.string().optional().describe("City name, e.g. San Francisco."),
+        category: z.string().optional().describe("Category filter, e.g. tacos, bakery, produce."),
+        type: z.string().optional().describe("Store type: restaurant, grocery, bakery, bodega, cafe, pharmacy, butcher, market, retail."),
+    }, async (args) => text(searchStores(loadRegistry(), args)));
+    server.tool("search_items", "Find a specific food or product across listed stores, e.g. 'birria tacos' or 'oat milk'. Pair with check_stock before telling a human a store has it.", {
+        query: z.string().describe("Item or food to find."),
+        city: z.string().optional().describe("Limit to one city."),
+    }, async ({ query, city }) => text(searchItems(loadRegistry(), query, city).map(({ store, item }) => ({ storeId: store.id, storeName: store.name, neighborhood: store.neighborhood, item }))));
+    server.tool("get_store", "Full listing for one store by registry id: hours, address, fulfillment, and every item with its last-confirmed stock status.", { store_id: z.string().describe("Registry id, e.g. sf-mission-taqueria-demo.") }, async ({ store_id }) => {
+        const store = getStore(loadRegistry(), store_id);
+        return text(store ?? { error: `No store with id ${store_id}` });
+    });
+    server.tool("check_stock", "Score how likely a store actually has an item right now. Returns a 0-100 score, a band (likely / probable / uncertain / unlikely), and the reasons. Never present an 'uncertain' or 'unlikely' verdict to a human as available.", {
+        store_id: z.string().describe("Registry id of the store."),
+        item: z.string().describe("Item name as listed, e.g. 'Birria tacos'."),
+    }, async ({ store_id, item }) => {
+        const reg = loadRegistry();
+        const store = getStore(reg, store_id);
+        if (!store)
+            return text({ error: `No store with id ${store_id}` });
+        const found = store.items.find((i) => i.name.toLowerCase() === item.toLowerCase())
+            ?? store.items.find((i) => i.name.toLowerCase().includes(item.toLowerCase()));
+        if (!found)
+            return text({ error: `${store.name} does not list '${item}'`, listedItems: store.items.map((i) => i.name) });
+        return text(stockLikelihood(store, found));
+    });
+    server.tool("validate_store", "Run the ShelfSignal validation checks on a listing and return its receipt: tier (VERIFIED / LISTED / STALE / INCOMPLETE), score, and every check with its evidence. Use this before recommending a store you have not used before.", { store_id: z.string().describe("Registry id of the store.") }, async ({ store_id }) => {
+        const store = getStore(loadRegistry(), store_id);
+        return text(store ? validateStore(store) : { error: `No store with id ${store_id}` });
+    });
+    server.tool("submit_store", "Validate a merchant submission (the $100 Starter Store intake) and preview exactly how it would appear in the registry, with its validation receipt. Does not charge anything and does not publish until the listing is merged into the registry.", { submission: z.record(z.unknown()).describe("The merchant submission object; see examples/submission.example.json for the shape.") }, async ({ submission }) => text(processSubmission(submission)));
+    server.tool("list_coverage", "Which cities and categories the index currently covers, with store counts. Check coverage before promising a human you can search somewhere.", {}, async () => {
+        const reg = loadRegistry();
+        return text({ cities: listCities(reg), categories: listCategories(reg), stores: reg.stores.length });
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+//# sourceMappingURL=mcp.js.map

package/dist/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"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"}

package/dist/registry.d.ts

@@ -0,0 +1,18 @@
+import type { Registry, Store } from "./types.js";
+/** Registry source of truth: registry/stores.json in the repo (v0.1, git-backed). */
+export declare function registryPath(): string;
+export declare function loadRegistry(path?: string): Registry;
+export declare function getStore(reg: Registry, id: string): Store | undefined;
+export declare function searchStores(reg: Registry, opts?: {
+    query?: string;
+    city?: string;
+    category?: string;
+    type?: string;
+}): Store[];
+export interface ItemHit {
+    store: Store;
+    item: Store["items"][number];
+}
+export declare function searchItems(reg: Registry, query: string, city?: string): ItemHit[];
+export declare function listCities(reg: Registry): string[];
+export declare function listCategories(reg: Registry): string[];

package/dist/registry.js

@@ -0,0 +1,67 @@
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Registry source of truth: registry/stores.json in the repo (v0.1, git-backed). */
+export function registryPath() {
+    const env = process.env.SHELFSIGNAL_REGISTRY;
+    if (env)
+        return env;
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        join(here, "..", "registry", "stores.json"),
+        join(here, "..", "..", "registry", "stores.json"),
+        join(process.cwd(), "registry", "stores.json"),
+    ];
+    for (const c of candidates)
+        if (existsSync(c))
+            return c;
+    return candidates[0];
+}
+export function loadRegistry(path = registryPath()) {
+    const raw = readFileSync(path, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed.stores))
+        throw new Error(`Registry at ${path} has no stores array`);
+    return parsed;
+}
+export function getStore(reg, id) {
+    return reg.stores.find((s) => s.id === id);
+}
+const norm = (s) => s.toLowerCase().trim();
+export function searchStores(reg, opts = {}) {
+    return reg.stores.filter((s) => {
+        if (opts.city && norm(s.city) !== norm(opts.city))
+            return false;
+        if (opts.type && norm(s.type) !== norm(opts.type))
+            return false;
+        if (opts.category && !s.categories.some((c) => norm(c).includes(norm(opts.category))))
+            return false;
+        if (opts.query) {
+            const q = norm(opts.query);
+            const hay = [s.name, s.type, s.city, s.neighborhood ?? "", ...s.categories, ...s.items.map((i) => i.name)].join(" ").toLowerCase();
+            if (!hay.includes(q))
+                return false;
+        }
+        return true;
+    });
+}
+export function searchItems(reg, query, city) {
+    const q = norm(query);
+    const hits = [];
+    for (const store of reg.stores) {
+        if (city && norm(store.city) !== norm(city))
+            continue;
+        for (const item of store.items) {
+            if (norm(item.name).includes(q) || norm(item.category).includes(q))
+                hits.push({ store, item });
+        }
+    }
+    return hits;
+}
+export function listCities(reg) {
+    return [...new Set(reg.stores.map((s) => s.city))].sort();
+}
+export function listCategories(reg) {
+    return [...new Set(reg.stores.flatMap((s) => s.categories))].sort();
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}

package/dist/submit.d.ts

@@ -0,0 +1,17 @@
+import type { Store } from "./types.js";
+import { validateStore } from "./validate.js";
+export interface SubmissionResult {
+    ok: boolean;
+    store: Store | null;
+    problems: string[];
+    receipt: ReturnType<typeof validateStore> | null;
+}
+/**
+ * Merchant intake. A store owner fills one JSON form (see
+ * examples/submission.example.json and docs/INTAKE.md); submit checks it the
+ * same way agents will see it, assigns the registry id, stamps the tier, and
+ * returns the validation receipt the merchant gets for their $100 starter.
+ * Payment itself happens outside the repo (Stripe link in docs/PRICING.md);
+ * nothing here charges a card.
+ */
+export declare function processSubmission(input: unknown, now?: Date): SubmissionResult;

package/dist/submit.js

@@ -0,0 +1,67 @@
+import { validateStore } from "./validate.js";
+const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48);
+/**
+ * Merchant intake. A store owner fills one JSON form (see
+ * examples/submission.example.json and docs/INTAKE.md); submit checks it the
+ * same way agents will see it, assigns the registry id, stamps the tier, and
+ * returns the validation receipt the merchant gets for their $100 starter.
+ * Payment itself happens outside the repo (Stripe link in docs/PRICING.md);
+ * nothing here charges a card.
+ */
+export function processSubmission(input, now = new Date()) {
+    const problems = [];
+    const raw = (input ?? {});
+    if (!raw.name || String(raw.name).trim().length < 2)
+        problems.push("name is required");
+    if (!raw.address || String(raw.address).trim().length < 5)
+        problems.push("address is required");
+    if (!raw.city || String(raw.city).trim().length < 2)
+        problems.push("city is required");
+    if (!raw.hours)
+        problems.push("hours are required");
+    if (!raw.type)
+        problems.push("type is required (restaurant, grocery, bakery, bodega, cafe, pharmacy, butcher, market, retail, other)");
+    if (!Array.isArray(raw.items) || raw.items.length === 0)
+        problems.push("at least one item is required");
+    if (Array.isArray(raw.items)) {
+        raw.items.forEach((item, idx) => {
+            if (!item?.name)
+                problems.push(`items[${idx}].name is required`);
+            if (item && (item.price === undefined || item.price === null))
+                problems.push(`items[${idx}].price is required (use the real shelf price)`);
+            if (item && !item.lastConfirmed)
+                problems.push(`items[${idx}].lastConfirmed is required (date you last confirmed it, YYYY-MM-DD)`);
+        });
+    }
+    if (problems.length)
+        return { ok: false, store: null, problems, receipt: null };
+    const today = now.toISOString().slice(0, 10);
+    const store = {
+        id: raw.id ?? `${slug(raw.city)}-${slug(raw.name)}`,
+        name: String(raw.name).trim(),
+        type: String(raw.type).trim(),
+        city: String(raw.city).trim(),
+        neighborhood: raw.neighborhood,
+        address: String(raw.address).trim(),
+        phone: raw.phone,
+        website: raw.website,
+        hours: String(raw.hours).trim(),
+        categories: Array.isArray(raw.categories) && raw.categories.length ? raw.categories.map(String) : [String(raw.type)],
+        fulfillment: Array.isArray(raw.fulfillment) && raw.fulfillment.length ? raw.fulfillment : ["walk_in"],
+        items: (raw.items ?? []).map((i) => ({
+            name: String(i.name),
+            category: String(i.category ?? raw.type),
+            price: i.price ?? null,
+            unit: i.unit,
+            stock: i.stock ?? "unknown",
+            lastConfirmed: String(i.lastConfirmed ?? today),
+            staple: Boolean(i.staple),
+            notes: i.notes,
+        })),
+        updatedAt: today,
+        tier: "starter",
+        demo: false,
+    };
+    return { ok: true, store, problems: [], receipt: validateStore(store, now) };
+}
+//# sourceMappingURL=submit.js.map

package/dist/submit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"submit.js","sourceRoot":"","sources":["../src/submit.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+export type StockStatus = "in_stock" | "low" | "out" | "unknown";
+export type Fulfillment = "pickup" | "walk_in" | "own_delivery" | "curbside";
+export interface StoreItem {
+    name: string;
+    category: string;
+    price: number | null;
+    unit?: string;
+    stock: StockStatus;
+    /** ISO date the merchant last confirmed this item, e.g. 2026-10-25 */
+    lastConfirmed: string;
+    staple?: boolean;
+    notes?: string;
+}
+export interface Store {
+    id: string;
+    name: string;
+    /** restaurant, grocery, bakery, bodega, cafe, pharmacy, butcher, market, retail, other */
+    type: string;
+    city: string;
+    neighborhood?: string;
+    address: string;
+    phone?: string;
+    website?: string;
+    /** free text, e.g. "Mon-Sun 8am-9pm" */
+    hours: string;
+    categories: string[];
+    fulfillment: Fulfillment[];
+    items: StoreItem[];
+    /** ISO date the listing itself was last updated by the merchant */
+    updatedAt: string;
+    /** starter = $100 listing tier; growth / pro reserved for later tiers */
+    tier: "starter" | "growth" | "pro";
+    /** true only for bundled sample data, never for a real merchant */
+    demo?: boolean;
+}
+export interface Registry {
+    version: number;
+    stores: Store[];
+}
+export type LikelihoodBand = "likely" | "probable" | "uncertain" | "unlikely";
+export interface StockVerdict {
+    storeId: string;
+    storeName: string;
+    item: string;
+    score: number;
+    band: LikelihoodBand;
+    reasons: string[];
+    lastConfirmed: string | null;
+    demo: boolean;
+}
+export type ValidationTier = "VERIFIED" | "LISTED" | "STALE" | "INCOMPLETE";
+export interface ValidationCheck {
+    name: string;
+    pass: boolean;
+    detail: string;
+}
+export interface ValidationReceipt {
+    storeId: string;
+    storeName: string;
+    tier: ValidationTier;
+    score: number;
+    checks: ValidationCheck[];
+    validatedAt: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/validate.d.ts

@@ -0,0 +1,13 @@
+import type { Store, ValidationReceipt } from "./types.js";
+/**
+ * Store validation: the receipt an agent (or a human) can check before
+ * trusting a listing. Same philosophy as the fleet's audit tools: a listing
+ * is only as good as its evidence, and the evidence is printed, not hidden.
+ *
+ * Tiers:
+ *  VERIFIED   every check passes and inventory was confirmed within 7 days
+ *  LISTED     complete profile, freshness between 8 and 30 days
+ *  STALE      complete profile but nothing confirmed in over 30 days
+ *  INCOMPLETE profile is missing something an agent needs to act on
+ */
+export declare function validateStore(store: Store, now?: Date): ValidationReceipt;

package/dist/validate.js

@@ -0,0 +1,48 @@
+import { daysBetween } from "./likelihood.js";
+/**
+ * Store validation: the receipt an agent (or a human) can check before
+ * trusting a listing. Same philosophy as the fleet's audit tools: a listing
+ * is only as good as its evidence, and the evidence is printed, not hidden.
+ *
+ * Tiers:
+ *  VERIFIED   every check passes and inventory was confirmed within 7 days
+ *  LISTED     complete profile, freshness between 8 and 30 days
+ *  STALE      complete profile but nothing confirmed in over 30 days
+ *  INCOMPLETE profile is missing something an agent needs to act on
+ */
+export function validateStore(store, now = new Date()) {
+    const checks = [];
+    const add = (name, pass, detail) => checks.push({ name, pass, detail });
+    add("name", store.name.trim().length >= 2, store.name || "missing");
+    add("address", store.address.trim().length >= 5, store.address || "missing");
+    add("city", store.city.trim().length >= 2, store.city || "missing");
+    add("hours", store.hours.trim().length >= 3, store.hours || "missing");
+    add("contact", Boolean(store.phone || store.website), store.phone || store.website || "no phone or website");
+    add("categories", store.categories.length >= 1, `${store.categories.length} categories`);
+    add("fulfillment", store.fulfillment.length >= 1, store.fulfillment.join(", ") || "none declared");
+    add("has_items", store.items.length >= 1, `${store.items.length} items listed`);
+    add("items_priced", store.items.length > 0 && store.items.every((i) => i.price !== null && i.price > 0), store.items.length ? `${store.items.filter((i) => i.price !== null && i.price > 0).length}/${store.items.length} items priced` : "no items");
+    const freshest = store.items.reduce((min, i) => Math.min(min, daysBetween(i.lastConfirmed, now)), Number.POSITIVE_INFINITY);
+    add("inventory_fresh", Number.isFinite(freshest) && freshest <= 30, Number.isFinite(freshest) ? `freshest item confirmed ${freshest}d ago` : "no confirmation dates");
+    const passed = checks.filter((c) => c.pass).length;
+    const score = Math.round((passed / checks.length) * 100);
+    const complete = checks.slice(0, 9).every((c) => c.pass);
+    let tier;
+    if (!complete)
+        tier = "INCOMPLETE";
+    else if (freshest <= 7)
+        tier = "VERIFIED";
+    else if (freshest <= 30)
+        tier = "LISTED";
+    else
+        tier = "STALE";
+    return {
+        storeId: store.id,
+        storeName: store.name,
+        tier,
+        score,
+        checks,
+        validatedAt: now.toISOString(),
+    };
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"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"}

package/docs/INTAKE.md

@@ -0,0 +1,30 @@
+# Merchant intake: what to submit
+
+Ten minutes, one form. This is everything a store needs to be listed and validated. The JSON template is `examples/submission.example.json`; a hosted form that emits the same shape is on the roadmap, and until then a store can send these answers in any format and we convert them.
+
+## About the store
+
+- **name**: exactly as it appears on your sign
+- **type**: restaurant, grocery, bakery, bodega, cafe, pharmacy, butcher, market, retail, or other
+- **address**: street address where customers show up
+- **city** and **neighborhood**
+- **phone** or **website**: at least one way to reach you (agents check this before recommending you)
+- **hours**: plain text is fine, e.g. "Mon-Sun 8am-9pm"
+- **categories**: the words customers and agents use for you: "tacos", "sourdough", "produce"
+- **fulfillment**: pickup, walk_in, own_delivery, curbside
+
+## Your stuff
+
+For each item (Starter covers up to 50):
+
+- **name**: what a customer would ask for
+- **price**: the real shelf price. Listings with missing prices fail validation.
+- **stock**: in_stock, low, out (be honest; agents score this, and a store that cries wolf decays)
+- **lastConfirmed**: the date you last laid eyes on it, YYYY-MM-DD
+- **staple**: true for everyday items you restock routinely
+
+## After you submit
+
+- You get a validation receipt: your tier and the checks behind it.
+- VERIFIED means complete and fresh. Keep items confirmed within 7 days to stay VERIFIED.
+- Refreshing stock is one message or one command. It is always free.

package/docs/MANAGEMENT.md

@@ -0,0 +1,24 @@
+# Management system
+
+ShelfSignal's management system is built around one idea: **the registry is the business, and freshness is the operations job.**
+
+## Source of truth
+
+`registry/stores.json` holds every listing. In v0.1 it lives in git: every new store, price change, and stock refresh is a diff a human reviewed. That is a feature at pilot scale (25-100 stores): zero infrastructure, full audit trail, no database to babysit.
+
+## The daily loop
+
+1. **Freshness scan**: `shelfsignal validate-all` re-scores every listing. Stores sliding from VERIFIED to LISTED (nothing confirmed in 8+ days) get a nudge list.
+2. **Merchant nudges**: one short message per stale store: "Your eggs were last confirmed 12 days ago; agents now see you as uncertain. Reply with today's stock to recover VERIFIED." The reply updates `lastConfirmed` and the affected items.
+3. **Intake queue**: new submissions run through `shelfsignal submit` before merge; failures go back to the merchant with the named problems from the validator, not a form rejection.
+4. **Agent-traffic log** (roadmap, Growth tier): record every `search_items` / `check_stock` query, aggregate weekly per store: what agents looked for, what the store had, what it missed. Misses are the merchant's best restock list and the sales proof for renewal.
+
+## Roles
+
+- **Operator (Rene)**: owns the registry, Stripe link, and merchant relationships. Approves merges.
+- **Merchants**: own their data. They can update or delist at any time; a delisted store leaves the registry in the next commit.
+- **Agents**: read-only. An agent can validate and quote receipts; it cannot edit a listing.
+
+## When it outgrows git
+
+At roughly 500 stores or the second city, move the same JSON schema into a hosted store (Postgres or a document DB) behind the same MCP tools, keep git as the export format, and give merchants the dashboard: stock board, freshness alerts, agent-traffic report. The MCP contract does not change, so agents never notice the move.

package/docs/PRICING.md

@@ -0,0 +1,26 @@
+# Pricing
+
+## Starter Store: $100, one time
+
+Everything a local store needs to be found by AI agents:
+
+- Full registry listing: profile, hours, address, fulfillment, categories
+- Up to 50 items with real prices and stock status
+- Validation run + public receipt (VERIFIED tier when fresh)
+- Stock-likelihood scoring on every item
+- Agent discovery through the ShelfSignal MCP server
+- Merchant update path (one command or one message to refresh stock)
+- One city, one location
+
+No commission on any sale, ever. No monthly fee to stay listed. A listing that goes stale decays in tier honestly; the merchant refreshes it for free.
+
+## Why flat, why $100
+
+Delivery apps charge 15-30% forever because they can. A listing is not worth 30% of a restaurant. $100 is priced so a bodega, a bakery, or a taqueria says yes in one conversation, and so 100 stores in one city is $10,000 of revenue with zero delivery fleet, zero couriers, and zero per-order cost. The business scales by city, not by order.
+
+## Roadmap tiers (not sold yet)
+
+- **Growth, $49/mo per location**: 500 items, multi-location, priority freshness reminders, menu and inventory file imports (CSV/POS exports), monthly agent-traffic report showing what agents searched for and whether the store had it.
+- **Pro / City Partner**: API keys for chains and market halls, bulk onboarding, city launch partnerships with business associations.
+
+Payment for Starter runs through a Stripe payment link. The repo never touches card data; `submit` validates the listing, Stripe validates the payment, the listing merges.

package/docs/SPEC.md

@@ -0,0 +1,47 @@
+# Spec
+
+## Problem
+
+AI agents are becoming the way people find things in a city ("find me birria tacos near the Mission that are actually available"). The data they need does not exist in a usable form:
+
+- Delivery apps hold menus hostage behind closed apps, ad ranking, and 15-30% commissions, with no stock information at all.
+- Map listings have hours and photos but no items, no prices, no stock.
+- Merchant websites are unstructured and go stale silently.
+
+## Product
+
+ShelfSignal is a merchant-submitted, agent-readable store index with three engines:
+
+1. **Registry** (`registry/stores.json`): the source of truth. One record per store: identity, location, hours, categories, fulfillment, and items with price, stock status, and last-confirmed date. v0.1 is git-backed so every change is a reviewable diff. A hosted registry with the same schema is the v0.3 roadmap item.
+2. **Likelihood engine** (`src/likelihood.ts`): deterministic scoring of the evidence behind "do they have it": reported status (in/low/out/unknown) adjusted by confirmation age and staple status. Output is score + band + reasons, designed to be quoted by the calling agent.
+3. **Validation engine** (`src/validate.ts`): 10 checks producing a receipt and a tier (VERIFIED / LISTED / STALE / INCOMPLETE). Agents call `validate_store` before recommending an unfamiliar store; merchants see the same receipt, so the fix list is never a mystery.
+
+Access is dual, matching the fleet pattern: one bin runs the CLI for operators and merchants, and the MCP server (`shelfsignal mcp`, stdio) for agents.
+
+## Intake flow
+
+1. Merchant fills the intake (JSON template in `examples/`, or a form that emits the same JSON; see INTAKE.md).
+2. Merchant pays the $100 Starter via Stripe payment link.
+3. `shelfsignal submit intake.json --write` validates and appends the listing; a bad intake fails with named problems, never a silent drop.
+4. The listing's first validation receipt is sent to the merchant: this is what agents will see.
+5. Updates: the merchant re-submits changed items or sends a stock ping; `updatedAt` and item `lastConfirmed` move, freshness recovers.
+
+## Trust rules
+
+- Bundled sample data is always `demo: true` and says so in every verdict.
+- Scores are computed from merchant-reported evidence only; the engine never invents stock.
+- An `uncertain` or `unlikely` verdict must never be presented to a human as available. The MCP tool description says this to every calling agent.
+- Ranking is validation tier and freshness. There is no paid ranking and there will not be.
+
+## Non-goals (v0.1)
+
+- No delivery, no couriers, no payments processing inside the repo.
+- No scraping of delivery apps or map platforms. Listings are merchant-submitted, period.
+- No ordering. Agents discover, validate, and direct; the transaction happens with the store. (Order-ahead intents are a roadmap item once merchants ask.)
+
+## Roadmap
+
+- v0.2: intake form page, Stripe link wiring, SF pilot: first 25 real stores onboarded by hand.
+- v0.3: hosted registry + merchant dashboard (stock board, freshness alerts, agent-traffic report).
+- v0.4: imports (CSV, Square/Toast exports), photo menu OCR intake.
+- v0.5: second city pack; business-association bundle pricing.

package/docs/VS-DOORDASH.md

@@ -0,0 +1,27 @@
+# ShelfSignal vs the delivery apps
+
+The delivery apps are not a discovery problem. They are a toll booth.
+
+| | DoorDash / Uber Eats model | ShelfSignal |
+|---|---|---|
+| Who owns the listing | The platform | The merchant |
+| What the merchant pays | 15-30% of every order, plus ads to rank | $100 flat, one time, to get listed |
+| Who owns the customer | The platform | The merchant (agents send people to the store) |
+| Menu truth | Rented, scraped, or stale partner feeds | Merchant-submitted, dated, decays when stale |
+| Stock truth | None. "Unavailable" discovered after ordering | Scored likelihood with reasons, before anyone moves |
+| How agents reach it | No open protocol; closed apps | Open MCP server, any agent can query |
+| Ranking | Pay to play | Validation tier and freshness only |
+| The store's tablet farm | Yes | No |
+
+## The different vertical
+
+ShelfSignal is not a delivery company and does not want to be one. Delivery is logistics; this is **agent commerce infrastructure**: the verified local inventory layer that every assistant, concierge agent, travel agent, and neighborhood bot will need before it can act in the physical city.
+
+The fight is not "deliver food faster." The fight is: **when an AI agent looks for something in the real world, whose index does it read, and who gets paid?** If the answer stays "the delivery apps' closed, ad-ranked, stock-blind index," local stores keep paying rent to be found in their own neighborhood. ShelfSignal makes the index open, merchant-owned, validated, and cheap enough that a bodega can afford to be found by machines.
+
+## What $100 buys that 30% never did
+
+- A permanent, agent-readable listing the merchant controls.
+- A validation receipt that makes agents trust and recommend the store.
+- Stock signals that bring in people who actually find what they came for.
+- Zero per-order tax on being successful.

package/examples/submission.example.json

@@ -0,0 +1 @@
+{"address":"123 Real Street, San Francisco, CA 94100","categories":["tacos","mexican"],"city":"San Francisco","fulfillment":["pickup","walk_in"],"hours":"Mon-Sun 9am-9pm","items":[{"category":"tacos","lastConfirmed":"2026-10-25","name":"Your signature item","price":12.5,"staple":false,"stock":"in_stock"},{"category":"drinks","lastConfirmed":"2026-10-25","name":"Your everyday staple","price":4.0,"staple":true,"stock":"in_stock"}],"name":"Your Store Name","neighborhood":"Your Neighborhood","phone":"(415) 555-0199","type":"restaurant","website":"https://yourstore.example.com"}

package/package.json

@@ -1,6 +1 @@
-{
-  "name": "@reneturcios/shelfsignal",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{"bin":{"shelfsignal":"dist/cli.js"},"dependencies":{"@modelcontextprotocol/sdk":"^1","zod":"^3"},"description":"The open store index for AI agents: local merchants list what they sell for a flat $100 starter, agents find real food and real stock nearby, and every listing carries a validation receipt. No 30% delivery-app cut.","devDependencies":{"@types/node":"^20","tsx":"^4","typescript":"^5"},"engines":{"node":">=20"},"files":["dist","server.json","registry","examples","docs"],"homepage":"https://github.com/CloudCorpRecords/shelfsignal#readme","license":"MIT","mcpName":"io.github.CloudCorpRecords/shelfsignal","name":"@reneturcios/shelfsignal","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/CloudCorpRecords/shelfsignal.git"},"scripts":{"build":"tsc","dev":"tsx src/cli.ts","test":"tsx --test test/*.test.ts"},"type":"module","version":"0.1.0"}

package/registry/stores.json

@@ -0,0 +1 @@
+{"stores":[{"address":"000 Demo Street, San Francisco, CA","categories":["tacos","mexican","burritos"],"city":"San Francisco","demo":true,"fulfillment":["pickup","walk_in"],"hours":"Mon-Sun 10am-10pm","id":"sf-mission-taqueria-demo","items":[{"category":"tacos","lastConfirmed":"2026-10-25","name":"Birria tacos","price":14.5,"staple":false,"stock":"in_stock"},{"category":"burritos","lastConfirmed":"2026-10-25","name":"Al pastor burrito","price":12.0,"staple":true,"stock":"in_stock"},{"category":"drinks","lastConfirmed":"2026-10-24","name":"Horchata","price":4.5,"staple":true,"stock":"low"}],"name":"Mission Taqueria (Demo)","neighborhood":"Mission District","phone":"(415) 555-0100","tier":"starter","type":"restaurant","updatedAt":"2026-10-25"},{"address":"000 Demo Avenue, San Francisco, CA","categories":["bakery","bread","pastries"],"city":"San Francisco","demo":true,"fulfillment":["walk_in","pickup"],"hours":"Tue-Sun 7am-3pm","id":"sf-sunset-bakery-demo","items":[{"category":"bread","lastConfirmed":"2026-10-25","name":"Sourdough loaf","price":9.0,"staple":true,"stock":"in_stock"},{"category":"pastries","lastConfirmed":"2026-10-25","name":"Cardamom knot","notes":"Weekends only, sells out by 10am","price":5.5,"staple":false,"stock":"out"}],"name":"Sunset Bakery (Demo)","neighborhood":"Outer Sunset","phone":"(415) 555-0101","tier":"starter","type":"bakery","updatedAt":"2026-10-25"},{"address":"000 Demo Boulevard, San Francisco, CA","categories":["groceries","snacks","drinks","pantry"],"city":"San Francisco","demo":true,"fulfillment":["walk_in"],"hours":"Mon-Sun 8am-11pm","id":"sf-richmond-bodega-demo","items":[{"category":"drinks","lastConfirmed":"2026-10-23","name":"Oat milk 64oz","price":5.99,"staple":true,"stock":"in_stock"},{"category":"pantry","lastConfirmed":"2026-10-20","name":"Farm eggs dozen","price":7.49,"staple":true,"stock":"low"},{"category":"pantry","lastConfirmed":"2026-09-28","name":"Tinned fish assortment","price":6.25,"staple":false,"stock":"unknown"}],"name":"Richmond Corner Bodega (Demo)","neighborhood":"Inner Richmond","phone":"(415) 555-0102","tier":"starter","type":"bodega","updatedAt":"2026-10-20"},{"address":"000 Demo Plaza, San Francisco, CA","categories":["produce","fruit","vegetables"],"city":"San Francisco","demo":true,"fulfillment":["walk_in"],"hours":"Tue, Thu, Sat 8am-2pm","id":"sf-ferry-market-produce-demo","items":[{"category":"vegetables","lastConfirmed":"2026-10-25","name":"Heirloom tomatoes 1lb","price":4.0,"staple":false,"stock":"in_stock","unit":"lb"},{"category":"fruit","lastConfirmed":"2026-10-25","name":"Persimmons 1lb","price":3.5,"staple":false,"stock":"in_stock","unit":"lb"}],"name":"Ferry Market Produce (Demo)","neighborhood":"Embarcadero","tier":"starter","type":"market","updatedAt":"2026-10-25","website":"https://example.com/ferry-market-produce-demo"}],"version":1}

package/server.json

@@ -0,0 +1 @@
+{"$schema":"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json","description":"The open store index for AI agents: local merchants list what they sell for a flat $100 starter, agents find real food and real stock nearby, and every listing carries a validation receipt.","name":"io.github.CloudCorpRecords/shelfsignal","packages":[{"environmentVariables":[],"identifier":"@reneturcios/shelfsignal","registryType":"npm","transport":{"type":"stdio"},"version":"0.1.0"},{"environmentVariables":[],"identifier":"ghcr.io/cloudcorprecords/shelfsignal:0.1.0","registryType":"oci","transport":{"type":"stdio"},"version":"0.1.0"}],"repository":{"source":"github","url":"https://github.com/CloudCorpRecords/shelfsignal"},"title":"ShelfSignal","version":"0.1.0"}