UAI 1 Website Export Contract

Version: 1.0.0

Metadata

Field	Value
Source site	protocol5.com
Source URL	https://protocol5.com/
Canonical AIWikis URL	https://aiwikis.org/protocol5/uai-system/files/spec-website-export-contract-md-27bd5148/
Source reference	spec/website-export-contract.md
File type	md
Content category	specification
Last fetched	2026-05-15T00:23:56.0837262Z
Last changed	2026-04-26T16:23:43.1208429Z
Content hash	sha256:27bd5148111c12a6738f92108fc6b9fa63531ca10650faf18be666b700a5b998
Import status	unchanged
Raw source layer	data/sources/protocol5/spec-website-export-contract-md-27bd5148111c.md
Normalized source layer	data/normalized/protocol5/spec-website-export-contract-md-27bd5148111c.txt

Current File Content

Structure Preview

• UAI-1 Website Export Contract
• 1. Purpose
• 2. Inputs
• 3. Export pipeline
• 4. Output obligations
• 5. File export contract
• 6. Routed endpoint contract
• 7. Failure behavior
• 8. Reference implementation mapping
• 9. Minimum conformance

Raw Version

Local absolute paths are redacted in this public view. The source hash and source-side raw layer are based on the unredacted source file.

# UAI-1 Website Export Contract

**Terminology:** UAI means **Universal Artificial Intelligence**. **UAI-1** means the current public UAI exchange contract published by UAIX.org.

Version: `1.0.0`

Status: Protocol5 package implementation reference

This document defines Protocol5 package behavior for pairing a human-facing website page with a UAI-1 machine representation. UAIX.org remains the public UAI-1 authority.

## 1. Purpose

A conformant website export flow turns rendered website content into authoritative UAI-1 without drift between the human page and the machine endpoint.

This contract applies to:

- build-time export pipelines
- file-to-file export jobs
- on-demand API or ASP.NET endpoint generation
- package-backed reference implementations

## 2. Inputs

A conformant exporter accepts:

- an HTML string or a readable HTML file
- translation options that identify the source page and export behavior

Published exporters MUST operate on the rendered page surface, not unpublished authoring fragments or private editor state.

For authoritative production output:

- `SourceUri` MUST be the stable public page URI
- `PageType` MUST be one of the canonical UAI page types
- `DocumentId` SHOULD be supplied explicitly; if derived, it MUST be deterministic for the same source URI and title
- `PreserveUnsupportedAsUnknown` SHOULD remain enabled
- if `ContentHash` is absent, exporters SHOULD compute one from the HTML bytes; the reference exporter uses `sha256:<hex>`

A file-path fallback such as `file:///...` is acceptable for local development, but it is not a substitute for the public `SourceUri` of a published page.

## 3. Export pipeline

A conformant exporter MUST execute these stages in order:

1. Load the HTML input as UTF-8 text.
2. Determine the effective source URI, document ID, title, language, and page type.
3. Translate the DOM according to translator-contract.md (source-relative: translator-contract.md).
4. Normalize the resulting document.
5. Validate the document before authoritative output is written or emitted.
6. Serialize canonical UTF-8 JSON only if validation succeeds.

## 4. Output obligations

A published export MUST:

- be valid UAI-1 JSON
- preserve literal source text according to the translator contract
- contain exactly one root `document` node whose id equals `documentId`
- include the required `source`, `metadata`, `structure`, `semantics`, `symbols`, `assets`, `relationships`, `annotations`, `provenance`, and `extensions` containers
- preserve unsupported constructs as `unknown` instead of dropping them silently
- preserve document-local symbols, assets, and relationships exactly as validated

## 5. File export contract

When exporting to disk:

- the output path SHOULD end with `.uai.json`
- paired public paths SHOULD follow a stable pattern such as `/docs/hello` and `/docs/hello/index.uai.json`
- the exporter MAY create missing output directories automatically
- the written file MUST be canonical UTF-8 JSON without post-write mutation

If the input path does not exist or cannot be read, export MUST fail.

## 6. Routed endpoint contract

A live UAI endpoint SHOULD:

- support `GET` and `HEAD`
- emit `Content-Type: application/uai+json; charset=utf-8; version=1.0.0`
- emit `X-UAI-1: 1.0` for legacy compatibility
- emit `Vary: Accept, X-UAI-1, Accept-Language`
- emit `Link` `describedby` references to the canonical registry and schema

The paired human page SHOULD advertise its machine representation through:

```html
<link rel="alternate" type="application/uai+json" href="/docs/hello/index.uai.json">
```

Reference websites using the Protocol5 .NET package MAY expose Protocol5 package artifacts so clients can reach `/UAI-1.json`, local mirror endpoints such as `/uai-1/registry`, `/uai-1/schema`, `/uai-1/validate`, compatibility aliases, and `/UAI-1/examples/...` without scraping HTML. Public UAI-1 authority remains on UAIX.org.

## 7. Failure behavior

If translation, normalization, or validation fails, the exporter MUST NOT publish the document as authoritative output.

Conformant implementations MUST:

- fail the build, export step, or HTTP request
- surface machine-readable validation codes and paths when available
- preserve unsupported fragments as `unknown` whenever safe preservation is possible

Implementations MUST NOT silently downgrade invalid output into best-effort authoritative JSON.

## 8. Reference implementation mapping

The reference .NET package satisfies this contract through:

- `UaiHtmlExporter.Export`
- `UaiHtmlExporter.ExportFile`
- `UaiHtmlExporter.ExportToFile`
- `MapProtocol5UaiHtmlEndpoint`
- `MapProtocol5UaiDocumentEndpoint`
- `MapProtocol5UaiCanonicalArtifacts`

The validator sample in `tools/Protocol5.UAI.Validator` is the reference smoke-test surface for checking exported files and the embedded canonical examples.

## 9. Minimum conformance

A website export implementation is conformant only if it:

1. produces valid UAI-1
2. preserves unsupported constructs through `unknown`
3. validates before publish or response emission
4. emits the canonical UAI media type for machine responses
5. keeps the human page and the machine page tied to the same stable public resource

Why This File Exists

This is a source file from protocol5.com. It is shown here because AIWikis.org is demonstrating the real source files that make the UAIX / LLM Wiki memory system work, not only summarizing those systems after the fact.

Role

This file is a focused source unit. Its path, headings, and metadata give an agent a retrieval handle that is smaller than loading the entire site or repository.

Structure

The file is structured around these visible headings: UAI-1 Website Export Contract; 1. Purpose; 2. Inputs; 3. Export pipeline; 4. Output obligations; 5. File export contract; 6. Routed endpoint contract; 7. Failure behavior. Those headings are retrieval anchors: a crawler or LLM can decide whether the file is relevant before reading every line.

Prompt-Size And Retrieval Benefit

Keeping this material in a separate file reduces prompt pressure because an agent can load this exact unit only when its role, source site, category, or hash is relevant. The surrounding index pages point to it, while this page preserves the full content for audit and exact recall.

How To Use It

• Humans should read the metadata first, then inspect the raw content when they need exact wording or provenance.
• LLMs and agents should use the source site, category, hash, headings, and related files to decide whether this file belongs in the active prompt.
• Crawlers should treat the AIWikis page as transparent evidence and follow the source URL/source reference for authority boundaries.
• Future maintainers should regenerate this page whenever the source hash changes, then review the explanation if the role or structure changed.

Update Requirements

When this source file changes, update the raw source layer, normalized source layer, hash history, this rendered page, generated explanation, source-file inventory, changed-files report, and any source-section index that links to it.

Related Pages

• Source overview
• UAI system index
• Source provenance
• Global File Index
• Reports

Provenance And History

• Current observation: 2026-05-15T00:23:56.0837262Z
• Source origin: current-source-workspace
• Retrieval method: local-source-workspace
• Duplicate group: sfg-117 (primary)
• Historical hash records are stored in data/hashes/source-file-history.jsonl.

Machine-Readable Metadata

{
    "title":  "UAI 1 Website Export Contract",
    "source_site":  "protocol5.com",
    "source_url":  "https://protocol5.com/",
    "canonical_url":  "https://aiwikis.org/protocol5/uai-system/files/spec-website-export-contract-md-27bd5148/",
    "source_reference":  "spec/website-export-contract.md",
    "file_type":  "md",
    "content_category":  "specification",
    "content_hash":  "sha256:27bd5148111c12a6738f92108fc6b9fa63531ca10650faf18be666b700a5b998",
    "last_fetched":  "2026-05-15T00:23:56.0837262Z",
    "last_changed":  "2026-04-26T16:23:43.1208429Z",
    "import_status":  "unchanged",
    "duplicate_group_id":  "sfg-117",
    "duplicate_role":  "primary",
    "related_files":  [

                      ],
    "generated_explanation":  true,
    "explanation_last_generated":  "2026-05-15T00:23:56.0837262Z"
}