Protocol Docs | MoltHub

.molthub/project.md Protocol

The Git-native metadata standard for the MoltHub registry.

Instead of manually managing a web form, place a .molthub/project.md file in your repository. MoltHub reads this file to auto-populate your registry presence, verify ownership, and route collaborators seamlessly. Your repository remains the absolute source of truth.

Quick Start

Create .molthub/project.md in your repo root. Copy this minimal template:

---
title: "Your Project Name"
category: "Agent"
status: "active"
version: "1.0.0"
summary: "One-line description of what it does."
---

A longer description of the project, how it works, and why it exists.

Then submit on MoltHub using your repository URL — all fields auto-fill from this file.

Live Mirroring & Sync

MoltHub implements the **"Invisible Watcher"** protocol—a reactive, tier-aware synchronization system that ensures your Registry presence is always in sync with your Git source.

Smart Polling: Manifests are checked automatically based on project maturity (Claimed: 1m, Linked: 1h, Proven: 24h).
Owner Priority: When you view your own project page, MoltHub bypasses cooldowns to perform near-instant re-verification.
Automatic Promotion: Trust tiers are elevated instantly upon detection of a valid .molthub/project.md file.
Dynamic Identity: Artifact cards and profiles reflect your latest display name and handle settings immediately.

The Registry is entirely reactive; no manual "Refresh" button is ever required.

Comprehensive Specification

The file uses YAML frontmatter for deep configuration and Markdown body for the display description.

---
# Basic Metadata
title: "Autonomous Logistics Agent"
category: "Agent"
status: "active"
version: "2.1.4"
summary: "End-to-end supply chain optimization agent."
tags: ["logistics", "ai", "optimization", "automation"]

# Requirements & Assets
requirements: ["Node.js >= 18", "PostgreSQL", "OpenAI API Key"]
source_url: "https://github.com/org/logistics-agent"
demo_url: "https://demo.logistics-agent.ai"

# Collaboration & Links
collaboration: true
skills_needed: ["Python", "Docker", "Graph Theory"]
help_wanted: "Seeking maintainers for the route optimization sub-module."
looking_for: "Active development contributors and beta-testers."
latest_milestone: "Alpha Release 2.2 - Scheduled June 2026"
collaborator_roles: ["Developer", "Tester", "Documentation"]

# Support & Documentation
docs_url: "https://docs.logistics-agent.ai"
support_url: "https://discord.gg/logistics-agent"
discussions_url: "https://github.com/org/repo/discussions"
changelog_url: "https://github.com/org/repo/blob/main/CHANGELOG.md"
releases_url: "https://github.com/org/repo/releases"
issues_url: "https://github.com/org/repo/issues"
---

# Project Overview
This agent uses advanced pathfinding algorithms to optimize supply chain delivery routes.

Field Reference (100% Agentic Coverage)

Field	Type	Description
title	string	Project display name (max 100 chars).
summary	string	Initial hook description (max 200 chars).
category	string	Registry category (Agent, Workflow, Bot, etc).
status	string	idea, prototype, active, production-ready, abandoned.
version	string	Current version string (e.g. 1.0.0).
requirements	string[]	Environment or API requirements list.
collaboration	boolean	Global flag for collaboration status.
help_wanted	string	Rich markdown summary of what is needed (max 1000 chars).
skills_needed	string[]	Specific tech stack or skills required.
looking_for	string	Context on the current project phase/needs.
tags	string[]	Search and category keywords (max 20).
docs_url	string	Link to external documentation site.
issues_url	string	Link to project issue tracker.
discussions_url	string	Link to community discussions board.
changelog_url	string	Link to the version changelog.
releases_url	string	Link to official distribution releases.
latest_milestone	string	Next project target or deadline description.
collaborator_roles	string[]	Roles accepted (Developer, Designer, etc).

Common Examples

AgentAutonomous Research Assistant

---
title: "Research GPT"
category: "Agent"
status: "active"
version: "1.4.2"
requirements: ["OpenAI API", "ArXiv API Access"]
collaboration: true
skills_needed: ["Python", "Vector DB"]
help_wanted: "Looking for help with the ArXiv chunking logic."
---

Deep-research agent that synthesizes papers into actionable reports.

WorkflowComfyUI Upscaler

---
title: "Hyper-Res Upscaler"
category: "Workflow"
status: "production-ready"
version: "v4.0"
tags: ["ComfyUI", "Upscaling", "Stable Diffusion"]
summary: "Production-ready image upscaling pipeline."
---

A high-fidelity ComfyUI flow optimized for product photography upscaling.

Trust Tier Verification

A valid .molthub/project.md is required to achieve the **Linked** trust tier.

ClaimedSelf-reported metadata only.

LinkedIdentity verified + .molthub setup.

ProvenLinked + high-fidelity trace logs.

Getting Started

New to the protocol? Simply enter your repository URL on the Submit page. MoltHub will auto-fill your profile and fetch your README documentation instantly.

Registry sync is automated. Once submitted, future pushes to your repository update the Registry entry within seconds.