Skip to main content

How ProductAtlas works

ProductAtlas separates authoring from distribution so that agents can consume reproducible knowledge without seeing unfinished work.

Current lifecycle​

Consumers browse and retrieve eligible immutable Releases through the public web, REST, and anonymous MCP. Signed-in Publishers use Publisher Studio for the authoring and publication path below.

  1. A Publisher—an individual or organization—owns a stable Blueprint.
  2. Authorized members edit its mutable, private Blueprint Draft and sections, upload supported assets, and save changes with revision protection.
  3. Studio previews deterministic structural readiness for one exact saved Draft revision. Preview does not approve, publish, or create trust evidence.
  4. An authorized, verified-email Publisher submits that exact revision with a semantic version, release notes, license, and attribution. ProductAtlas stores an immutable submission snapshot and evaluates that snapshot.
  5. A structurally eligible submission enters human review. Changes requested lead back to the mutable Draft and a new submission; approval authorizes a later Publisher action but does not publish automatically.
  6. An authorized Publisher uses Publish release to create an immutable Blueprint Release that is public or unlisted. Publishing never changes an earlier Release.
  7. After publication, an authorized Publisher can add, edit, or clear reversible deprecation guidance, or withdraw a Release permanently. An administrator can restore only an administrator-withdrawn Release; Publisher withdrawal is terminal.

Each Release snapshot carries its exact content, license, attribution, dependencies, publication metadata, and deterministic content digest, plus any eligible safe asset references and scoped evidence available for that Release. A correction therefore becomes a new version; the historical Release remains addressable.

From discovery to adaptation​

Public search indexes eligible Release metadata, not Drafts, withdrawn content, unlisted Releases, or private assets. Search returns compact summaries so a consumer can choose a match before retrieving full content.

The anonymous public MCP flow is:

MCP client
  -> Streamable HTTP /mcp
  -> search_blueprints, get_blueprint, or get_blueprint_markdown
  -> public catalog application service
  -> immutable Blueprint Release

search_blueprints supports text plus exact metadata filters and opaque pagination cursors. get_blueprint resolves an optional exact version and returns summary, standard, or complete detail. See the tool reference for the implemented contract.

Boundaries that stay visible​

  • Trust signals describe a specific check and subject; they do not guarantee that a Blueprint is correct or that an implementation will be secure.
  • Publisher-authored text and assets remain untrusted even after authentication, scanning, or human review.
  • Anonymous MCP is read-only and contains no draft or publication tools.
  • RavenDB stores application documents; Cloudflare R2 stores binary assets. Only eligible public derivatives can be referenced by a public Release.

Planned extensions​

  • Deeper customer-facing asset upload, processing, and safety-pipeline guidance are Planned. Release availability alone must not be read as proof that a particular scanner ran.
  • Semantic or AI quality evaluation is Planned. Current Studio quality is a deterministic structural-readiness score.
  • Production Proven remains a future evidence process and is never inferred from a Publisher claim, human review, or publication.