kickstart: m2-market spec discovery — concept v0.2 + verified system map

Working title m2-market. Seeds: unified concept paper (work store, Solutions,
credits, Solution Scout, cargstore-as-storefront) and a verified map of how
m2-gpt (bifrost gateway, tenancy/metering), agent.memory.system (memory-api/
Qdrant/BGE-M3), and the m2o Coolify fleet (Hermes primary agent, herdr, RDP,
openclaw-open) actually connect. specs/ awaits discovery output.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
m2 (AI Agent) 2026-07-02 01:03:39 +02:00
commit 14b5543ebf
3 changed files with 374 additions and 0 deletions

242
CONCEPT.md Normal file
View file

@ -0,0 +1,242 @@
# 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 35 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."

46
README.md Normal file
View file

@ -0,0 +1,46 @@
# m2-market
**Working title** for the M2 Marketplace — the platform for packaged work. Operators package
repeatable outcomes as installable **Solutions**, sell them to other operators for **M2
credits**; a **Solution Scout** proposes the right package in-session at the moment of need;
Hermes composes build-vs-install proposals with cost evidence. *"The unit is not software.
The unit is completed work."*
## Status: spec discovery (kickstarted 2026-07-01)
| Doc | Purpose |
|---|---|
| [CONCEPT.md](CONCEPT.md) | Unified concept paper v0.2 (pitch v0.1 + fedlearn rails + cargstore + Scout) |
| [context/SYSTEM-MAP.md](context/SYSTEM-MAP.md) | How m2-gpt, agent.memory.system, m2o/Coolify, Hermes/OpenClaw actually connect (verified) |
| [specs/](specs/) | Spec-kit style discovery output lands here (spec → clarify → plan → tasks) |
## The one-paragraph architecture
Marketplace = **protocol + registry, not one app**. Forgejo (`git.machinemachine.ai`) is the
system of record (listings = releases, review = PRs, veto = labels); **memory-api** indexes it
semantically (`market:catalog` partition, same BGE-M3 hybrid search as agent memory);
**cargstore** (revived → M2 Store) renders it in-desktop; **Hermes** speaks it in-session
(backed by **m2-gpt**, whose tenant keys/budgets/metering seed the **m2-ledger** credit
economy); the **fedlearn sync path** installs it (signed, idempotent, tenant-aware). The only
genuinely new services: `m2-ledger` (append-only internal credits) and the `Solution Scout`
(per-desktop watcher → semantic match → toast + deep link → few-clicks deploy).
## Dependencies
- **fedlearn MVP** (in execution): schemas, `m2/m2-core`, memory-api auth, curator+veto,
`m2-core-sync`. The marketplace is its commercial tier — same rails, plus price/seller/license.
- Existing: m2-gpt (tenancy+metering) · agent.memory.system (catalog+evidence) · m2o fleet
(surface) · cargstore (storefront) · Forgejo (registry) · Coolify (deploys).
## Open forks (need operator decision — CONCEPT.md §14)
1. Ledger substrate: standalone m2-ledger (rec.) vs extend m2-gpt billing vs Forgejo-as-ledger
2. Pricing v1: fixed per install (rec.) vs metered vs both
3. Storefront: cargstore Electron revival (rec.) vs web-first vs both
4. Scout host: standalone supervised watcher (rec.) vs Hermes plugin vs herdr plugin
5. Seed Solutions: mm-pdf · agent-scaffold · competitor-scan (proposed)
6. Platform cut % + starter grant (defaults 10% / 100 cr)
## Next steps
1. Resolve the 6 forks (or accept recommendations).
2. Run spec discovery per subsystem → `specs/` (spec-kit or GSD; herdr herd like the fedlearn
discovery: one angle-specialist per subsystem — ledger, catalog, store UI, Scout, packaging).
3. Wait for fedlearn MVP convergence (schemas + sync path are hard inputs to `solution.schema`).

86
context/SYSTEM-MAP.md Normal file
View file

@ -0,0 +1,86 @@
# System Map — how the existing stack connects (verified 2026-07-01)
The marketplace composes three live systems plus the m2o fleet. All run as **Coolify apps on
the m2 host**, on the shared `coolify` Docker network — services reach each other by Docker
DNS alias, humans/external agents via Traefik-routed domains.
```
┌────────────────────────── m2 host (Coolify) ──────────────────────────┐
│ │
operator browser ──► Guacamole (m2o.machinemachine.ai) │
│ │ VNC/RDP via per-desktop guacd:4822 │
│ ▼ │
│ m2o desktops (primus: chris/matrix/m2bd/erlengrund · │
│ agent-latest: sdjs/nasr/parlobyg/peter/gunnar) │
│ │ each: Hermes gateway (supervised) + herdr + [openclaw on legacy] │
│ │ │
│ ├── LLM calls ──► m2-gpt gateway (gpt.machinemachine.ai/v1) │
│ │ Bifrost/FastAPI, multi-tenant keys, per-tenant │
│ │ budgets/metering, "subconscious" middleware: │
│ │ injects m2.* memory tools + ambient context ──┐ │
│ │ │ │
│ └── memory ops ──► memory-api:8000 (agent.memory.system) ◄──────┘ │
│ FastAPI + Qdrant (BGE-M3 hybrid) + memgraph │
│ + TEI embeddings + redis; agent_id partitions; │
│ public: memory.machinemachine.ai │
│ │
│ Forgejo (git.machinemachine.ai) — org m2; fedlearn m2/m2-core (WIP) │
└────────────────────────────────────────────────────────────────────────┘
```
## The three repos
### 1. m2-gpt — github.com/machine-machine/m2-gpt (local: /home/m2/m2-gpt/m2-gpt)
Multi-tenant **OpenAI-compatible gateway with a subconscious layer**. Any OpenAI-speaking
harness (Hermes, OpenClaw, Claude Code) points `base_url` at `https://gpt.machinemachine.ai/v1`
with a tenant key; the gateway routes to upstreams (SGLang on spark cluster, OpenRouter, GLM)
and injects `m2.*` memory tool-calls + ambient sensation into the prompt. Live:
`{"status":"healthy","gateway":"bifrost"}`; two gateway containers (staging+prod pattern).
**Marketplace relevance:** tenant identity, per-tenant budgets and token metering (the natural
substrate/federation point for `m2-ledger`), admin APIs/UI (React/shadcn — reusable patterns
for a market admin), fleet_standards cascade resolver.
### 2. agent.memory.system — github.com/machine-machine/agent.memory.system (local: /home/m2/agent.memory.system)
The memory stack behind `memory-api`. Python FastAPI over **Qdrant (BGE-M3 dense+sparse
hybrid) + memgraph (graph) + TEI embeddings + redis**; working/episodic/semantic memory with
consolidation + importance scoring. Deployed twice via Coolify (stacks `z1rlou…` and `vc00o…`
— the known split-brain; fedlearn task T13 is resolving auth + live-endpoint discovery now).
Consumed by: desktops (m2-memory skill, openclaw memory-engine plugin), m2-gpt backings
(`backings/` HTTP client), fedlearn partitions (`fedlearn:submissions|clusters|core-index`).
**Marketplace relevance:** the semantic catalog (`market:catalog` partition), pricing-evidence
recall, Scout intent-matching — all one more partition on proven infra.
### 3. m2o — github.com/machine-machine/m2o (local: /home/m2/m2o)
The desktop platform: Guacamole gateway + primus image (`desktop/`) + provision.sh +
fleet.json. Every desktop ships **Hermes as primary agent** (supervised gateway, config
rendered on first boot pointing at m2-gpt with `M2_GPT_API_KEY` injected at provision) +
**herdr** baked fleet-wide (v4.4+) + **RDP standard** (v4.5). Legacy agent-latest desktops
additionally run **openclaw** (m2-custom fork) with the memory-engine plugin.
**Marketplace relevance:** the execution surface (installs land in `/agent_home` volumes via
the fedlearn sync path), the co-driving wedge (Guacamole VNC/RDP), Scout host, cargstore host.
## Agent posture
- **Hermes = the gateway-managed primary agent** (every primus desktop; supervised; m2-gpt
backed). The marketplace's conversational surface (`market-propose` skill) targets Hermes
FIRST.
- **OpenClaw = open option** (legacy desktops run it; m2-gpt explicitly serves both). Design
marketplace touchpoints harness-agnostic where cheap: anything speaking OpenAI-wire through
m2-gpt inherits the subconscious/memory layer, so Scout/propose logic should live behind the
gateway or as skills, not inside one harness.
## Related moving parts
- **fedlearn MVP (in herd execution now):** builds the rails the marketplace rides —
schemas, Forgejo `m2/m2-core`, memory-api auth hardening, capture CLI, curator+veto PRs,
`m2-core-sync` apply path. Plan: `/home/m2/m2o/.planning/federated-learning/PLAN.md`.
- **cargstore** (github.com/machine-machine/cargstore): Electron+React desktop app store
(Flatpak backend, JSON catalog, one-click installs, agent WebSocket) → evolve into M2 Store.
- **Coolify** (cool.machinemachine.ai): deploys everything above; new marketplace services
(m2-ledger, catalog indexer, Scout) should be Coolify apps on the `coolify` network. Gotcha:
the local registry route self-redirects (302), so primus-style images build local-only.
- **spark cluster** (spark16): SGLang upstreams for m2-gpt; future Resource inventory.
## Hard constraints inherited
- Tenant isolation (sdjs=GST etc.): client data never crosses into shared catalog/core.
- No secrets in repos/images; keys injected at runtime (M2_GPT_API_KEY pattern).
- Mixed images (primus vs agent-latest): runtime-sync is the only universal install path.
- Host fragility: canary-first rollouts, idempotent + reversible applies, no fleet-wide blast.