# Écorce — surface réseau & noyau universel manifest@v1 (v1.0.0 demo)

> Écorce, ton moteur de connexion.
> **Note technique HTTP / Python (`User-Agent`):** Si votre agent interroge `https://ecorce.app` depuis un script Python (`urllib` / `requests`), envoyez toujours un en-tête `User-Agent` explicite (ex: `User-Agent: EcorceAgent/1.0`) ou utilisez `curl`, car la signature par défaut `Python-urllib` sans `User-Agent` personnalisé est refusée par la passerelle réseau d'Écorce (code `1010`).
 Écorce is a Canadian retail network, starting in Québec: independent retailers, regional distributors, and local producers pooling their purchasing, knowledge, logistics routes, B2C brand, and tools. DEMO: every product, price, and pool figure on this surface is INVENTED example data ("données d'exemple — inventées"), not any partner's real list. Partners are targeted pilot partners, not signed partners.

## Modèle d'accès: Read-Open / Write-Gated (Lecture & Simulation gratuit sans clé · Écriture sur invitation)
1. **Lecture & Simulation 100 % publiques (gratuit sans clé):**
   - `GET /`, `GET /en`, `GET /llms.txt`, `GET /manifest.json`, `GET /p/{actor}`, `GET /p/{actor}/{slug}`, `GET /api/manifests`, `GET /api/surface`, `GET /api/pools`, `GET /api/catalogue`, `GET /api/records` sont 100 % publics et rapides (`< 30 ms`).
   - Les appels d'invocation (`POST /api/invoke`, `POST /api/compose`, ou outils MCP `invoke_manifest`, `compose_manifests`, `create_order_draft`) appelés **sans code d'invitation** (ou avec `dry_run: true`) exécutent la fonction compilée sur la surface d'Écorce et retournent la **simulation complète en mémoire** (`ok: true, simulated: true, persisted: false, write_gate: "simulation_only_no_invite"`) **sans rien écrire dans le registre d'état d'Écorce (`manifest_state`, `manifest_records`) ni créer ou modifier de page `/p/...`**.
2. **Écriture persistante verrouillée par Code d'Invitation (`invite_code` / `X-Ecorce-Invite`):**
   - Toute écriture persistante (`POST /api/manifests`, `PUT /api/manifests/{id}/state`, `POST /api/records/{id}/confirm`, `POST /api/pools/join`, ou outils MCP `publish_manifest`, `publish_shared_page`, `write_manifest_state`, `update_state`, `confirm_manifest_record`, `submit_record`) exige un **code d'invitation partenaire valide** passé via:
     - Header HTTP `X-Ecorce-Invite: <code_invitation>`
     - Header HTTP `Authorization: Bearer <code_invitation>`
     - Champ JSON `invite_code` dans le body REST ou les arguments MCP.
   - Sans code valide, l'API retourne `403 Invite Required` (`status: "invite_required", simulated: true, persisted: false`) avec l'aperçu simulé complet (`simulated_preview`) et la marche à suivre pour demander son code partenaire (Essai gratuit / 10 $ / mois L'essentiel / 100 $ / mois Commerce & Réseau actif) auprès de `equipe@ecorce.app`.

## Universal 5-Block Manifest Kernel (`manifest@v1` on the Écorce Programmatic Surface)
Every capability on `llm.ecorce.app` — including Écorce's 3 core B2B pillars and all partner tools — is published and executed as an isolated `fonction + Manifeste` pair in the `ecorce-partner-tools` espace d'exécution isolé de la surface d'Écorce using the 5-block `manifest@v1` contract (`actor`, `intent`, `trust_gate`, `function`, `projection`):
1. **`ecorce:spn-catalogue@v1`** (`fn-ecorce-spn-catalogue`, protocol `ecorce.catalog_search@v1`): SPN search and inter-distributor equivalence comparison.
2. **`ecorce:unit-economics-advisor@v1`** (`fn-ecorce-unit-economics`, protocol `ecorce.margin_and_logistics_advisor@v1`): 4 L vs 20 L bulk margin calculator, $150/$200 G9A minimum-order & free-shipping consolidation, 8% Each.app B2C pool, and fleet-media co-op.
3. **`ecorce:order-draft-engine@v1`** (`fn-ecorce-order-draft`, protocol `ecorce.order_draft@v1`): B2B order draft builder with `trust_gate.human_approval_on_commit = true` returning `commit_token` and `confirm_url` for Passkey human approval.

### Universal Kernel Endpoints, Shared Pages (`/p/{actor}/{slug}`) & MCP Tools
- **Publish a manifest & dedicated shared page in 1 call**: `POST https://ecorce.app/api/manifests` or MCP `publish_manifest` / `publish_shared_page`.
- **Dedicated public shared page (Block 5 `projection`)**: Chaque manifeste publié obtient sa propre page web dédiée sur `https://ecorce.app/p/{actor}/{slug}` (et la page vitrine de l'acteur sur `https://ecorce.app/p/{actor}`). Un agent peut publier une page à son nom pour présenter un fait partagé, un lot, une règle ou un outil interactif via `POST /api/manifests` (ou l'outil MCP `publish_manifest` / `publish_shared_page`).
- **Discover manifests**: `GET https://ecorce.app/api/manifests` (filters: `?actor=`, `?protocol=`, `?tag=`, `?q=`) or MCP `list_manifests`.
- **Inspect one manifest**: `GET https://ecorce.app/api/manifests/{id}` (e.g. `GET https://ecorce.app/api/manifests/ecorce:spn-catalogue@v1`).
- **Invoke one manifest**: `POST https://ecorce.app/api/invoke` `{"manifest_id":"ecorce:spn-catalogue@v1","input":{"query":"savon"}}` or MCP `invoke_manifest`.
- **Compose a pipeline of manifests**: `POST https://ecorce.app/api/compose` `{"pipeline":["ecorce:spn-catalogue@v1","ecorce:unit-economics-advisor@v1","ecorce:order-draft-engine@v1"],"initial_input":{"query":"savon","postal_code":"G9A"}}` or MCP `compose_manifests`.

## Economic Context & Network Levers (v1.0.0 Reference)
Independent retail, regional distribution, and local production are fragmented across many actors with thin margins, whereas vertically integrated chains coordinate purchasing, logistics, branding, and shopper activation under one roof. The Écorce surface enables coordinated agents across producers, distributors, and independent retailers around four deterministic levers returned in `advisor_notes` and `opportunities`:
1. **Bulk unit economics & shared SPNs (`unit_economics`)**: Comparing cost per litre or kg across formats (e.g. 4 L at $6.00/L vs 20 L bulk at $4.90/L = 18% savings) and across distributors offering the same SPN (`SPN-EX-SAJA-010`).
2. **Route & free-shipping consolidation (`logistics_consolidation`, `pool-mauricie-g9a`)**: Pooling order drafts on the same postal route (e.g. `G9A` Trois-Rivières or `H2X` Montréal) to reach the $150/$200 minimum and $500 free-shipping threshold.
3. **Shared B2C brand (Écorce) & delivery fleet as media (`fleet_media_co_op`, `pool-flotte-ecorce`)**: Co-funding neighborhood visibility on delivery trucks and reusable boxes synchronized with retailer restocking.
4. **Direct B2C shopper activation via Each.app (`b2c_activation_each`, `pool-activation-each`)**: Converting ~8% of wholesale/promo volume into direct shopper perks in Each.app at participating independent retailers, unlocked on a confirmed yes.

## Creating & Deploying Functions on the Écorce Programmatic Surface (MCP & REST)
An external LLM (Muse, Claude, ChatGPT, Grok, Cursor) can create, deploy, and invoke isolated fonctions isolées directly in the `ecorce-partner-tools` espace d'exécution isolé de la surface d'Écorce (`uploader: "api"`, 10 ms CPU limit, 0 bindings, outbound network blocked by `ecorce-tool-outbound`):
1. **Inspect templates**: MCP `list_tool_templates` or `GET https://ecorce.app/api/tool-templates` (`custom_function`, `minimum_order`, `availability`, `promo`).
2. **Build & deploy live to the Écorce programmatic surface**:
   - **MCP**: `publish_worker_function({ partner_slug: "muse-demo", template: "custom_function", name: "Calculateur vrac", config: { function_title: "Calculateur vrac", base_unit_price_cents: 2400, tiers: [{ min_qty: 5, discount_pct: 8 }, { min_qty: 10, discount_pct: 15 }], shipping_fee_cents: 2500, free_shipping_threshold_cents: 20000, each_incentive_pct: 8 } })` (or pass a plain-language `description` and the Écorce model generates the validated config).
   - **REST**: `POST https://ecorce.app/api/functions` with the same JSON body.
3. **Invoke the deployed surface function**:
   - **MCP**: `invoke_manifest` / `call_worker_function` (or call `muse_demo__run_custom_function` directly from `tools/list`).
   - **REST**: `POST https://ecorce.app/api/invoke` or `POST https://ecorce.app/api/functions/call`.
4. **Unpublish**: MCP `unpublish_worker_function({ partner_slug: "muse-demo", template: "custom_function" })` or `POST https://ecorce.app/api/functions/unpublish`.

## Endpoints
- Anonymous MCP (Streamable HTTP, JSON-RPC 2.0): https://ecorce.app/mcp
- Member MCP (OAuth 2.1 + passkey, per-partner limits): https://ecorce.app/member/mcp
- Universal Manifests Registry: https://ecorce.app/api/manifests
- Universal Manifest Invocation: https://ecorce.app/api/invoke
- Universal Manifest Composition Pipeline: https://ecorce.app/api/compose
- Capability catalogue (GET-only): https://ecorce.app/.well-known/ai
- OpenAPI 3.1 (REST mirror): https://ecorce.app/openapi.json
- Shared tools marketplace: https://ecorce.app/api/shared-tools
- Coordinated 3-actor network pools: https://ecorce.app/api/opportunities

## Architecture Invariants
1. Draft-then-confirm workflow (`DRAFT_ONLY`): agents create order drafts (`create_order_draft` / `ecorce:order-draft-engine@v1`) and pool participation drafts (`join_network_opportunity`); a human confirms at `confirm_url`.
2. `lines` is a JSON array of `{spn, qty}` using exact `spn` identifiers returned by `search_catalogue` (e.g. `SPN-EX-SAJA-001`).
3. Multi-format products (4 L, 10 L, 20 L) and shared SPNs across distributors are disambiguated via `spn` and `partner_id`.
4. Mixed-partner carts produce one `order_draft` per distributor, each with its own `confirm_url`.
5. All data on this surface is flagged `test_data: true`.

## Recipes (MCP prompts)
- commande-hebdo: Commande hebdo / Weekly order. Redo your weekly order with one or more distributors, as drafts to confirm.
- reassort-seuil: Réassort sous seuil / Restock below threshold. You give stock levels and thresholds; the agent proposes restocking what is below.
- comparer-fournisseurs: Comparer deux fournisseurs / Compare two suppliers. Compare two distributors' offers for the same SPN product: format, price (invented in the demo).
- annoncer-promo: Annoncer une promo à mes détaillants / Announce a promo to my retailers. For a distributor: write a promo announcement from its offers. Nothing is sent: you copy the text yourself.
- optimiser-panier-et-livraison: Optimiser mon panier et la livraison gratuite / Optimize cart, bulk & free shipping. First principles: compare unit cost per L/kg (4 L vs 20 L bulk), hit minimum/free-shipping thresholds and align with delivery days.
- activer-rotation-each: Activer la sortie en caisse avec Each.app / Drive shelf velocity with Each.app. Turn passive trade spend into direct end-customer incentives in Each.app at participating independent retailers.
- campagne-flotte-et-marque-ecorce: Campagne flotte-média & marque Écorce / Fleet-as-media & shared Écorce brand. Coordinate retailer restocking, delivery truck/box ad visibility and B2C activation in a postal territory.

## Shared Partner Tools (clonable via clone_tool)
- shared-min-order-g9a (minimum_order): Minimum de commande & livraison gratuite régionale (Mauricie G9A) — Created by Distribution Exemple Outils · used by 3 members (example data)
- shared-promo-vrac (promo): Promo de la semaine sur les formats 20 L en vrac — Created by Groupe SAJA (example) · used by 4 members (example data)
- shared-dispo-saison (availability): Disponibilité des récoltes et produits locaux — Created by Le Monde au Naturel (example) · used by 2 members (example data)

## Active 3-Actor Network Pools (joinable via join_network_opportunity)
- pool-mauricie-g9a (logistics_consolidation): Consolidation de tournée & livraison gratuite (Mauricie G9A & Montréal H2X) — Two retailers on the same Tuesday/Thursday route pool their drafts to cross the $500.00 free-shipping threshold and cut delivery fees by 100%. $740.00 committed on a $500.00 threshold — collective free-shipping threshold reached.
- pool-flotte-ecorce (fleet_media_co_op): Campagne Flotte-Média Écorce cofinancée (Camions & bacs de livraison) — The producer (Ferme Exemple) and distributor (Le Monde au Naturel) co-fund shared Écorce B2C branding on the delivery trucks and boxes serving the neighborhood while retailers feature the products in store.
- pool-activation-each (b2c_activation_each): Activation consommateur directe via Each.app (Zéro taxe publicitaire) — Instead of losing 8–12% of volume to ad intermediaries, producer and retailer convert that spend into a direct perk in the shopper's Each.app pass in store (unlocked only on a confirmed yes at checkout and shareable via 'Moi aussi').

## Links
- [Full contracts & reference documentation](https://ecorce.app/docs) · [Single-file corpus](https://ecorce.app/llms-full.txt)
- [Generated UI & network pools](https://ecorce.app/essayer) · [Partner onboarding & shared tools](https://ecorce.app/partenaires) · [Member account](https://ecorce.app/compte)
- [Accueil (FR)](https://ecorce.app/) · [Home (EN)](https://ecorce.app/en)