MSP-1 - AI-friendly semantics for trusted information.

Enterprise & Development Network

MSP-1 Repository Declarations

Status: Labs Concept — Implementable
Protocol: MSP-1 v1.0.2
Scope: Repository-level semantic context
Artifact: Root-level msp.json
Applicable Tools: Repository Declaration Builder

Overview

MSP-1 Repository Declarations apply the existing MSP-1 site-level declaration model at the root of a version-controlled repository.

The purpose is simple: provide a capable model or agent with semantic context before it begins deeper inspection of repository contents.

A repository already exposes a bounded collection of artifacts at a stable web location. A root-level msp.json can identify that location and declare the repository's name, purpose, provenance, authority, canonical location, revision context, and optional interpretive framing.

The declaration does not replace repository inspection. It improves the starting point for it.

The Ingestion-Point Problem

When an agent encounters an unfamiliar repository, it commonly begins by examining artifacts such as:

  • README.md
  • package or dependency manifests
  • directory structure
  • documentation
  • configuration files
  • source code
  • releases and datasets

From those artifacts, it gradually infers what the repository is, why it exists, and how its contents should be interpreted.

That works, but the process begins with inference.

MSP-1 provides a publisher-declared semantic anchor before deeper inspection starts.

repository/
├── msp.json
├── README.md
├── LICENSE
├── src/
├── docs/
└── ...

The repository-root declaration gives the consumer high-signal context at the boundary where the repository is first encountered.

Repository Placement

For this concept, the MSP-1 declaration is placed at the repository root:

/msp.json

This is a repository-local placement convention.

It does not replace or redefine the web discovery endpoint:

/.well-known/msp.json

The well-known path remains the canonical discovery location for conventional website-level deployment.

A repository-root msp.json instead travels with the repository itself and remains available when the repository is cloned, mirrored, archived, or opened by another compatible agentic tool.

Declaration Model

Repository declarations use the existing MSP-1 site context:

"@context": "https://msp-1.org/context/msp-1-site.jsonld"

and the existing site-level type:

"@type": "MSPSite"

The repository's canonical web location can serve naturally as both its stable identifier and primary URL.

Example:

{
  "@context": "https://msp-1.org/context/msp-1-site.jsonld",
  "@type": "MSPSite",
  "protocol": {
    "name": "MSP-1",
    "version": "1.0.2"
  },
  "site": {
    "id": "https://github.com/example/project",
    "name": "Example Project",
    "url": "https://github.com/example/project",
    "canonical": {
      "url": "https://github.com/example/project"
    },
    "description": "Reference implementation and supporting materials for Example Project.",
    "intent": "Provide version-controlled source, documentation, and implementation resources.",
    "interpretiveFrame": {
      "frame": "Interpret this repository as the canonical development and reference surface for Example Project.",
      "category": "informational",
      "scope": "repository"
    }
  },
  "provenance": {
    "type": "original",
    "source": "https://github.com/example/project",
    "confidence": "medium"
  },
  "revision": {
    "id": "repo-rev-1",
    "revisionDate": "2026-09-29",
    "revisionNotes": "Initial repository-root MSP-1 declaration.",
    "revisionVersion": "1.0.0"
  }
}

The example is intentionally conservative. Optional fields should be used only when they provide meaningful, supportable context.

Why site Works

Within MSP-1, site functions as the top-level semantic entity that establishes identity, location, purpose, and shared context for resources within it.

A repository fits that model naturally.

Its web URL identifies a bounded location, while the repository contains multiple subordinate artifacts such as source files, documentation, datasets, configuration, and releases.

The consuming model already understands from the surrounding environment that the location is a repository. MSP-1 does not need a separate repository-specific core term to restate what the consumer can reliably infer.

The declaration instead supplies the semantic information that should not be left entirely to inference.

Optional Interpretive Scope

A repository does not need to declare itself explicitly as a repository in every case.

When an interpretiveFrame is useful, its optional scope can clarify how broadly that framing applies:

"interpretiveFrame": {
  "frame": "Interpret this repository as a versioned reference dataset surface.",
  "category": "informational",
  "scope": "repository"
}

If no special interpretive framing is needed, the entire interpretiveFrame block may be omitted.

The repository type remains evident from the environment and canonical location.

Less Inference Before Deeper Inspection

A repository-root declaration changes the first stage of model orientation.

Without MSP-1:

repository encountered
        ↓
inspect artifacts
        ↓
infer identity and purpose
        ↓
build semantic frame
        ↓
reason over repository

With MSP-1:

repository encountered
        ↓
read msp.json
        ↓
establish semantic frame
        ↓
inspect artifacts
        ↓
reason over repository

MSP-1 does not replace reasoning.

It reduces unnecessary inference before reasoning begins.

This may be especially useful for large repositories, unfamiliar codebases, datasets, protocol repositories, documentation collections, and other artifact-heavy projects.

Declarative Context, Not Agent Instructions

Repository-level MSP-1 serves a different role from agent instruction files.

Files such as AGENTS.md, Copilot instructions, or model-specific configuration generally tell an agent how to work:

Use these commands.
Follow these coding conventions.
Build the project this way.

MSP-1 remains declarative:

This is what this repository represents.
This is why it exists.
This is its provenance and authority context.
This is how its contents should be interpreted.

The two approaches can coexist.

Operational instructions guide behavior.

MSP-1 provides semantic orientation.

Model-Agnostic by Design

A root-level msp.json is not tied to a specific coding assistant or model provider.

It can travel with the repository across:

  • GitHub
  • GitLab
  • self-hosted Git
  • local clones
  • archives
  • mirrors
  • agentic development environments
  • future repository-aware tooling

This makes the declaration portable semantic context rather than model-specific configuration.

Canonical Identity and Citation Normalization

The MSP-1 canonical term can be especially useful when repositories are mirrored, forked, moved, or exposed through multiple locations.

Example:

"url": "https://git.example.net/project",
"canonical": {
  "url": "https://github.com/example/project"
}

The current location remains visible, while the declaration identifies the preferred reference point.

For AI indexing, retrieval, citation, and provenance systems, this can help normalize multiple representations around a stable canonical resource.

Content Correlation

A consuming system may compare the declaration with the repository it actually observes.

This is not a security function and MSP-1 does not certify repository behavior.

However, a declaration provides an explicit semantic baseline. Alignment between declared purpose and observed contents can reduce ambiguity, while material contradictions remain available to the consuming system as evidence during its own reasoning.

MSP-1 declares.

The consumer evaluates.

Repository-Wide Context Is Usually Sufficient

This concept does not assume that every artifact inside a repository needs its own MSP-1 declaration.

The root-level declaration establishes repository-wide context.

Individual artifacts can normally be interpreted within that context unless a finer-grained declaration is materially useful.

This avoids turning repository clarity into metadata administration.

The guiding principle is:

Granularity should follow semantic difference, not filesystem structure.

Implementation Workflow

A minimal implementation is straightforward:

  1. Create or generate an MSP-1 site-level declaration.
  2. Use the repository's canonical web URL for site.id and site.url unless a distinct stable identifier is needed.
  3. Add high-signal repository context such as name, description, and intent.
  4. Add interpretiveFrame only when meaningful framing is useful.
  5. Add supported provenance, authority, trust, canonical, and revision metadata where appropriate.
  6. Save the declaration as msp.json at the repository root.
  7. Validate the declaration against the MSP-1 v1.0.2 site schema.
  8. Commit the file with the repository.

Tooling

An MSP-1 Repository Declaration Builder can reduce implementation to a short guided workflow:

repository URL
      ↓
identity and meaning
      ↓
optional provenance / authority / framing
      ↓
review
      ↓
download msp.json
      ↓
commit at repository root

This lowers adoption friction while preserving normal MSP-1 semantics.

Potential Integration Surface

Repository declarations can be consumed by any tool capable of reading MSP-1.

Potential integration points include:

  • coding agents
  • repository assistants
  • repository indexing systems
  • dependency analysis systems
  • AI retrieval pipelines
  • development environments
  • repository creation workflows
  • archive and provenance systems

The concept does not require native platform support.

Platform support would simply make the declaration easier to create, discover, or consume.

Design Principle

Repository-level MSP-1 follows the same broader principle as web deployment:

Give the consuming agent useful semantic context at the point of ingestion, then let it reason over the underlying artifact.

The protocol does not need to describe what the consumer can already understand from the environment.

It declares the context that benefits from being explicit.

Status

This concept is implementable with MSP-1 v1.0.2 using the existing site-level declaration model and vocabulary.

No repository-specific core term or protocol modification is required for implementation.

The repository-root placement convention can be adopted independently by publishers, developers, tools, and platforms while remaining model-agnostic and compatible with the existing MSP-1 declaration architecture.