docs(protocol): add material status schema and endpoint

README.md

@@ -5,154 +5,32 @@
 [![Discussions](https://img.shields.io/github/discussions/local-loop-io/loop-protocol)](https://github.com/local-loop-io/loop-protocol/discussions)
 [![Specification](https://img.shields.io/badge/spec-v0.1-orange.svg)](SPECIFICATION.md)
 
-> Local Optimization with Overflow Protocol - Infrastructure for planetary-scale circular economy
+Local Optimization with Overflow Protocol. A federated circular economy concept with shared schemas and interoperability notes.
 
-## 🌍 What is LOOP Protocol?
+> Early-stage, low-TRL concept. No public pilots or deployments. Lab demo only.
 
-LOOP Protocol proposes a federated circular economy network that preserves local sovereignty. Think of it as "email for materials" — a conceptual framework where cities could run interoperable nodes and exchange materials via shared standards.
-
-### Core Components
-
-- **🧬 MaterialDNA (proposed)**: Universal identification for any material or batch
-- **💰 LoopCoin (proposed)**: Expiring local currency that incentivizes circulation
-- **📡 LoopSignal (proposed)**: Democratic preferences that shape material flows
-- **💸 LoopCost (proposed)**: Transparent calculation including all penalties
-
-## 🚀 Quick Start
-
-### For Cities
-```bash
-# Prototype-only example (no official images yet)
-# docker run -p 8080:8080 localloop/node:latest
-```
-
-### For Developers
-
-```javascript
-// Proposed SDK interface (no public SDK published yet)
-// npm install @local-loop/sdk
-
-// Example client usage (illustrative only)
-const loop = new LoopClient('https://example.loop');
-
-// Register material
-const material = await loop.registerMaterial({
-  category: 'plastic-pet',
-  quantity: { value: 1000, unit: 'kg' },
-  quality: 0.95
-});
-```
-
-#### Schema Validation
+## What is here
+- `SPECIFICATION.md`: core protocol spec.
+- `schemas/`: JSON Schema definitions.
+- `examples/`: sample payloads for interop.
+- `contexts/`: JSON-LD contexts.
+- `rfcs/`: RFCs and design notes.
 
+## Quickstart
 ```bash
-npm install
+npm ci
 npm test
 ```
 
-## 📋 Specification
-
-Read the full LOOP Protocol Specification v0.1.1 (lab demo baseline)
-
-### Design Goals
-
-- **Federated Architecture**: No central authority required
-- **Economic Incentives**: Communities keep value from circular behaviors
-- **Democratic Control**: Citizens vote on trade preferences
-- **Transparent Routing**: Materials find optimal destinations
-- **Open Standards**: JSON-LD based, REST APIs
-
-## 🏗️ Implementations
-
-Implementations are exploratory and may not be publicly available yet. If you
-are building one, open an issue or RFC so we can link it here.
-
-## 🧪 Test Network
-
-No public test network is available yet. This is an early, low-TRL concept and the
-reference materials here are for specification and lab-only research demonstrations.
-
-## 🤝 Contributing
-
-We welcome contributions! See CONTRIBUTING.md for guidelines.
-
-### How to Contribute
-
-1. Read the specification
-2. Check [open issues](https://github.com/local-loop-io/loop-protocol/issues)
-3. Start a discussion in GitHub Discussions
-4. Submit RFCs for protocol changes
+## Usage notes
+- Specs and schemas are draft and subject to change.
+- No certified implementations exist at this time.
+- Use `examples/` to validate tooling and docs.
 
-## 🧭 Governance (Lab Stage)
+## Links
+- Docs hub: https://local-loop-io.github.io
+- Backend API: https://loop-api.urbnia.com
 
-- RFC workflow: `docs/governance/rfc-process.md`
-- RFC index: `rfcs/README.md`
-
-## 📚 Resources
-
-Public resources are still being assembled. For now, use GitHub Discussions and
-the repository documentation.
-
-- Specification: `SPECIFICATION.md`
-- API reference: `openapi.json`
-- Security guide: `docs/security-guide.md`
-- Federation handshake: `docs/federation-handshake.md`
-- Threat model: `docs/compliance/threat-model.md`
-- DPIA lite: `docs/compliance/dpia-lite.md`
-
-## 🎯 Roadmap
-
-### v0.1.1 (Current)
-
-- ✅ Minimal interop flow (MaterialDNA → Offer → Match → Transfer)
-- ✅ Reference documentation and schemas
-- ⏳ Prototype implementations (lab demo in progress)
-
-### v0.2 (Planned)
-
-- Smart contract integration
-- Advanced routing algorithms
-- Mobile SDKs
-- Pilot deployments with research partners (if/when available)
-
-### v1.0 (Planned)
-
-- Stable protocol
-- Aspirational multi-city adoption
-- Ecosystem marketplace
-- Carbon credit integration
-
-## 📊 Adoption
-
-There are no public pilots or deployments at this time. We are actively seeking
-collaboration partners and research contributors.
-
-## ⚖️ License
-
-MIT License - see LICENSE for details
-
-## 🙏 Acknowledgments
-
-- Inspired by [ActivityPub](https://www.w3.org/TR/activitypub/) for federation
-- [Carlsson & Nevzorova](https://doi.org/10.1016/j.clet.2025.100911) for MaterialDNA concept
-- The circular economy community worldwide
-
----
-
-_Building the material internet, one city at a time_ 🏙️
-
-## How to Cite
-
-If you reference this repository, please cite:
-Alphin Tom. "LOOP Protocol Specification and Schemas." LocalLoop, GitHub repository, 2025-2026. https://github.com/local-loop-io/loop-protocol
-
-```bibtex
-@misc{localloop_protocol_2025,
-  author = {Alphin Tom},
-  title = {LOOP Protocol Specification and Schemas},
-  year = {2025},
-  howpublished = {GitHub repository},
-  url = {https://github.com/local-loop-io/loop-protocol},
-  note = {Accessed 2025-12-19}
-}
-```
+## Contributing
+- Use `rfcs/` for feedback and proposals.
+- See `../AGENTS.md` for org context and domain policy.

SPECIFICATION.md

@@ -595,6 +595,38 @@ Response: 200 OK
 }
 ```
 
+#### Material Management (Lab Demo Extensions)
+
+The following endpoint is optional and used by the LocalLoop lab demo only. It is not required for protocol compliance.
+
+**POST /api/loop/material-status**
+
+```http
+POST /api/loop/material-status
+Content-Type: application/ld+json
+X-API-Key: {api-key}
+
+{
+  "@context": "https://local-loop-io.github.io/projects/loop-protocol/contexts/loop-v0.1.1.jsonld",
+  "@type": "MaterialStatusUpdate",
+  "schema_version": "0.1.1",
+  "id": "3c9a6a0b-8c1a-4d3f-9c2c-3c1c2f9d5c2a",
+  "material_id": "DE-MUC-2025-PLASTIC-B847F3",
+  "status": "reserved",
+  "updated_at": "2025-06-03T09:15:00Z",
+  "reason": "Reserved by city exchange",
+  "notes": "Holding until pickup is confirmed",
+  "source_node": "lab-hub.loop",
+  "metadata": { "ticket": "LAB-42" }
+}
+
+Response: 201 Created
+{
+  "id": "3c9a6a0b-8c1a-4d3f-9c2c-3c1c2f9d5c2a",
+  "created_at": "2025-06-03T09:15:05Z"
+}
+```
+
 #### Node Information
 
 **GET /api/v1/node/info**

examples/09-material-status.json

@@ -0,0 +1,15 @@
+{
+  "@context": "https://local-loop-io.github.io/projects/loop-protocol/contexts/loop-v0.1.1.jsonld",
+  "@type": "MaterialStatusUpdate",
+  "schema_version": "0.1.1",
+  "id": "3c9a6a0b-8c1a-4d3f-9c2c-3c1c2f9d5c2a",
+  "material_id": "DE-MUC-2025-PLASTIC-B847F3",
+  "status": "reserved",
+  "updated_at": "2025-06-03T09:15:00Z",
+  "reason": "Reserved by city exchange",
+  "notes": "Holding until pickup is confirmed",
+  "source_node": "lab-hub.loop",
+  "metadata": {
+    "ticket": "LAB-42"
+  }
+}

examples/README.md

@@ -11,6 +11,7 @@ This directory contains JSON examples that validate against the schemas in `sche
 - `06-offer.json`: Minimal interop offer payload (v0.1.1).
 - `07-match.json`: Minimal interop match payload (v0.1.1).
 - `08-transfer.json`: Minimal interop transfer payload (v0.1.1).
+- `09-material-status.json`: Material status update payload (v0.1.1 lab demo).
 
 ## Validation
 Run `npm test` from the repository root to validate all examples.