m2-market/CONCEPT.md

# M2 Marketplace — Unified Concept Paper

*Version 0.2 — 2026-07-01. Merges the M2 Platform Concept v0.1 (pitch + long-form), the
fedlearn-rails extension (v0.2 supersedes the earlier CONCEPT.md, see git history), the
existing **cargstore** asset, and the **Solution Scout** in-session proposal agent.*

---

## 0. One line

**M2 is a work store**: operators package repeatable outcomes as installable **Solutions**,
sell them to other operators for **M2 credits**, and an in-session **Solution Scout** proposes
the right package at the exact moment an operator needs it — few clicks to deployed.

---

## 1. Problem (compressed)

AI work is rebuilt from scratch: good sessions disappear into chat history; supply (skills,
tools, GPUs, operators, agencies) is fragmented; nobody remembers whether a request is a
10-minute job, a 2-day build, or already-solved inventory. The missing product is a system
that **remembers, packages, routes, prices, and sells repeatable work.**

## 2. Primitives

**Solution** — the sellable unit. An installable bundle of:
`intent + agent behavior (prompts/skills/playbooks) + tools (MCP/APIs/connectors) + runtime
(Hermes/desktop/browser/Guacamole/OpenClaw) + memory schema + permissions + deployment recipe
+ price + evidence`.

**Capability** — a repeatable kind of work (bookkeeping, agentic ops, sales work, marketing
audits, creative build, analysis, support). Capability is the supply; Solution is the packaged
outcome; Hermes composes both.

**Four inventory types in one catalog:**

| Type | What | Examples |
|---|---|---|
| Solutions | packaged outcomes | eBay listing workflow, bookkeeping flow, competitor scan |
| Capabilities | repeatable work categories | bookkeeping, research, support, creative |
| Resources | capacity M2 can spend against | GPUs, model endpoints, browser sessions, vision workers, hosting |
| Services | human/operator/agency units | setup, audit, migration, design pass, website build |

The buyer never thinks in these terms — they describe the outcome; M2 composes inventory.

---

## 3. What we already have (the asset map)

This is the decisive point: **almost every component already exists in our stack.** The
marketplace is an assembly job, not a greenfield build.

| Marketplace component | Existing asset | Gap to close |
|---|---|---|
| **Package format + registry of record** | fedlearn `m2-core-manifest` + artifacts in Forgejo `m2/m2-core` (MVP in execution NOW) | `solution.schema.json` superset: price, seller, license, revenue split |
| **Install path** (signed, idempotent, role/tenant-aware) | `m2-core-sync` / `m2-core pull --apply` + state.json (fedlearn W4) | pre-install ledger debit + license grant |
| **Semantic catalog + search** | memory-api/Qdrant, `fedlearn:core-index` partition | `market:catalog` partition; listing records |
| **Pricing evidence** ("10 min or 2 days?") | fedlearn submissions carry provenance (machine, session, herdr runs, tokens/time) | aggregate per-job cost telemetry onto listings |
| **Trust/curation pipeline** | auto-curate → scored PR → human veto → merge | third disposition: `commercialize`; listing review = same PR/veto |
| **Storefront UI (in-desktop)** | **cargstore** (github.com/machine-machine/cargstore): Electron+React store, JSON catalog, one-click install, persistent-volume storage, WebSocket agent integration, update manager, `web/` variant | swap Flatpak backend for Solution installs; point catalog at `market:catalog`; rebrand Clawdbot→M2 |
| **Conversational surface / proposal engine** | Hermes baked into every primus desktop; m2-memory skill for similar-work recall | `market-propose` skill (search + cost-estimate + build-vs-install paths) |
| **In-the-moment discovery** | herdr (session/lifecycle awareness, baked fleet-wide), openclaw session events | **Solution Scout** agent (§5) |
| **Execution surfaces** | m2o desktops (Guacamole VNC/RDP), embeddable workspace, herdr worker herds | permission modes: observe/suggest/take-control/hand-back |
| **Identity + tenancy** | fleet.json + tenant map (sdjs→gst, …), operator = human over N machines | `operator_id` + wallet |
| **Payments rail (internal)** | m2-gpt gateway already meters tokens/tenants | `m2-ledger` (small append-only credit service) — the one genuinely new component |
| **Distribution to mixed fleet** | fedlearn propagation design (bake vs runtime-sync vs config) | none — Solutions ride runtime-sync |

**Cargstore verdict:** don't build a new storefront — *evolve cargstore into the M2 Store*.
Its catalog schema (`id/name/summary/category/icon/featured/keywords` + install ref) maps
1:1 onto Solution listings; its install manager + persistent-volume pattern is exactly the
Solution deployment UX; its agent WebSocket channel is the hook the Scout needs to deep-link
"install this" proposals. The `web/` variant seeds the browser-facing marketplace later.

## 4. Where the marketplace lives (options considered)

| Option | Verdict |
|---|---|
| (a) **Cargstore evolution** — in-desktop store app | ✅ the *storefront surface*, not the system of record |
| (b) **Forgejo-native** — repos/releases as registry, PRs as review | ✅ the *registry of record* (versioned, signed, veto-gated) |
| (c) **memory-api catalog** — Qdrant partition + CLI | ✅ the *semantic index* (search/recommend), never the truth |
| (d) Hosted web marketplace (public site) | later — grows out of cargstore `web/` once inventory exists |
| (e) Third-party (npm-style registry, Stripe store) | ❌ loses the memory/evidence moat and tenant model |

**Answer: the marketplace is a protocol + registry, not one app.** Forgejo holds truth
(listings = repo releases, review = PRs, veto = labels); memory indexes it for meaning;
cargstore renders it in the desktop; Hermes + the Scout speak it in-session; the CLI
(`m2-market`) automates it. Same layering that won for fedlearn (git = truth, memory = index)
— one architecture, two tiers (free core / paid market).

---

## 5. The Solution Scout (in-session proposal agent)

The user's envisioned moment: *an operator is mid-session, starts building something a
Solution already solves — and an agent proposes the link right then; few clicks; deployed.*

**Mechanics (all existing rails):**

1. **Watch** — the Scout runs per-desktop (supervised, like hermes-gateway). Inputs, in
   privacy order: herdr lifecycle/run summaries (already structured), Hermes/OpenClaw session
   summaries, optionally window titles. **Never raw keystrokes; never raw client data.**
2. **Match** — periodically (or on "agent started working on X" events) embed the current
   intent summary and query `market:catalog` semantically (same BGE-M3 path as memory recall).
   Matching runs against tenant-allowed listings only.
3. **Propose** — on a high-confidence hit, a non-blocking toast (herdr notification or XFCE
   notify) + a cargstore **deep link**: *"This looks like 'eBay Listing Workflow' (12 installs,
   ★4.6, ~70% coverage, 40 credits). Install?"* Also surfaced in Hermes chat if that's the
   active channel.
4. **Deploy** — click → cargstore Solution page (evidence, price, permissions diff) →
   *Install* → ledger debit → license grant → `m2-core-sync` applies the bundle → Scout
   reports back "installed, here's how to invoke it."
5. **Learn** — accepted/dismissed proposals feed back as evidence (proposal→install
   conversion is a listing quality signal; dismissals tune the Scout's threshold).

**Guardrails:** opt-in per desktop (`pull-policy.toml`), rate-limited (max N proposals/day),
tenant-scoped matching, on-box summarization before anything leaves the machine, and the
Scout can only *propose* — the install click is always the human's.

This is the marketplace's demand-side engine: instead of hoping operators browse a store,
the store meets them at the moment of need.

## 6. Hermes as proposal engine (pull-side complement to the Scout)

The Scout is push-in-the-moment; Hermes is pull-on-request. User: *"I want to automate my
eBay listing process."* Hermes: searches memory (similar past work + real cost) and the
catalog (Solutions/Capabilities/Resources/Services), then proposes paths **with evidence**:

> "From scratch: ~2 days / ~8M tokens. Existing inventory covers ~70%: browser automation,
> listing workflow, product image generation. Three paths: install+adapt (40 cr, today),
> operator-assisted (120 cr, 2 days), full custom (est. 300 cr, 1 week)."

Approve → agents/operators/resources execute → completed work becomes new evidence and,
where repeatable, new inventory. **Every serious job leaves behind:** what was wanted, tools
used, who contributed, tokens/time/resources spent, what failed/succeeded, and whether a
Solution/Capability should be created or updated. That record is the pricing intelligence —
and the moat (§10).

---

## 7. Economy — M2 Credits

- **Internal ledger first** (`m2-ledger`: append-only tx `{ts, from, to, amount, reason:
  install|payout|grant|route|earn, ref}`, balances derived, X-API-Key auth, daily balance
  snapshot committed to Forgejo for audit). **No public coin/exchange** until worth the
  legal/tax/custody/fraud complexity.
- **Actors:** users buy outcomes · builders publish · operators deliver · resource owners
  sell capacity · agents spend within budgets. One identity may be several.
- **Value routing:** install → debit buyer, credit seller minus platform cut (default 10%,
  configurable). Operator work and resource usage settle through the same ledger. Payouts
  manually reconciled at first.
- **Earning credits** (participant economy): publishing reusable Solutions, testing Solutions,
  structured feedback, data labeling, paid surveys, contributing resources. Bootstrap: starter
  grants to active operators; platform earns cut only.
- **Agent budgets:** agents spend credits within operator-set budgets (m2-gpt gateway already
  meters tokens per tenant — the ledger federates with it rather than duplicating).

## 8. Resource & infrastructure marketplace

Spare capacity we already run (GPU boxes, spark nodes, vision/generation workers, browser
sessions, hosting) becomes internal supply: an agent needing batch visual checks routes to
internal vision workers instead of a random external API. Priced in credits through the same
ledger; listed as `Resource` inventory in the same catalog.

## 9. Co-driving workspace (the visible wedge)

The embeddable remote workspace — Guacamole/VNC/browser desktop + M2 side pane + shared
context — with permission modes **observe / suggest / take control / hand back**. Not the
platform; one execution surface. Example: a bookkeeping Solution opens the desktop, logs into
a portal, extracts documents, asks approval, hands back a report. Our m2o gateway + primus
fleet + RDP/VNC standard *is* this wedge's infrastructure, already live.

## 10. Positioning, moat, operators

- **Not** an app store / plugin market / cloud marketplace / agency / agent framework — parts
  of all: **a work store.** Buyers buy completed work; the unit is not software, it's outcomes.
- **Moat:** accumulated operational memory + packaged inventory + cost history + operator
  network + deployment/permission layer + credit economy. Each completed job strengthens
  future proposals — the compounding loop.
- **Operators & multiple M2s:** an operator runs personal/client/specialist M2 instances and
  fleets of agents; delivers client jobs; packages the repeatable ones back into the
  marketplace. `Client job → delivered → packaged → reused → operator earns from future use.`

## 11. Free core vs paid market (the boundary)

Fleet-standard infra learnings (Xorg self-heal, RDP standard, …) stay **free in shared
m2-core** — the commons that keeps the fleet healthy. Outcome-shaped packages become priced
Solutions. Curation gains a third disposition: `promote-to-core (free) | commercialize (list)
| reject/park`. Tenant-derived work can be commercialized **only** owner-initiated and
doubly-scrubbed; raw client data never crosses the tenant firewall.

---

## 12. First wedge (concrete, on our fleet)

Sequenced behind the fedlearn MVP (its rails are the dependency — in herd execution now):

1. **Schemas:** `solution.schema.json` + `listing.schema.json` (manifest superset; frozen v1).
2. **`m2-ledger`** on the host (SQLite, API, starter grants, platform cut, snapshot-to-git).
3. **Curation `commercialize` disposition** + listing PR template (evidence + price +
   permissions + rollback), riding the existing veto pipeline.
4. **`market:catalog`** partition + `m2-market search|show|install` CLI (install = ledger tx →
   existing sync/apply).
5. **Cargstore revival:** point catalog at `market:catalog`, add a Solution install backend
   beside Flatpak, rebrand → **M2 Store**; deploy on canaries (chris-m2o, gunnar-m2o).
6. **Package 3–5 real Solutions** from proven outcomes: mm-pdf branded-report generator,
   agent-scaffold workspace generator, competitor-scan report, client-site template,
   bookkeeping document assistant.
7. **Solution Scout v0** on one canary: herdr-run summaries → catalog match → toast + deep
   link (propose-only, opt-in).
8. **One real paid install** between two operators (e.g. m2bd buys sdjs-operator's package).

**Success:** a Solution listed with evidence → discovered via Scout or Hermes → bought with
credits → installed through the standard apply path → ledger reflects it → install telemetry
lands back in memory as pricing evidence. The loop closes commercially once.

## 13. Top risks

| Risk | Mitigation |
|---|---|
| Commons erosion (everything monetizes) | policy: fleet-infra learnings always free; curation enforces boundary |
| Client-data leakage via productization | owner-initiated only, double scrub, tenant firewall unchanged |
| Junk/fake listings | provenance refs required; PR/veto review; ratings + conversion signals on listings |
| Scout = surveillance creep | opt-in, on-box summarization, no raw keystrokes, rate-limited, propose-only |
| Ledger trust | append-only + daily snapshot to Forgejo; internal-only scope |
| Two-sided cold start | seed supply from our own proven outcomes; Scout drives demand at moment of need; starter grants |

## 14. Open forks (operator decisions)

1. **Ledger substrate:** standalone `m2-ledger` (recommended) vs extend m2-gpt gateway billing vs Forgejo-as-ledger.
2. **Pricing v1:** fixed per install (recommended) vs metered vs both.
3. **Cargstore path:** revive as Electron in-desktop store (recommended) vs web-first vs both at once.
4. **Scout host:** standalone supervised watcher (recommended) vs Hermes plugin vs herdr plugin.
5. **First Solutions to package** (proposed: mm-pdf, agent-scaffold, competitor-scan).
6. **Platform cut % + starter grant size** (defaults: 10%, 100 cr).

## 15. The simple story

- **Customers:** "Tell M2 what you want done. It finds what exists, estimates cost, proposes the best path, executes."
- **Builders:** "Package repeatable work once. Earn whenever M2 routes demand to it."
- **Operators:** "Deploy outcomes faster; every successful project becomes sellable inventory."
- **Resource owners:** "Offer spare compute/models/workers as routable capacity."
- **M2:** "Every job makes the platform smarter, cheaper, and more valuable."