UAIX Specification v1.0

This is a draft source note behind the public Project Handoff page. For launch truth, AGENTS.md, readme.human, README.md, docs/current-reference.md, docs/deploy.md, and docs/roadmap.md win when they confli...

Metadata

Field	Value
Source site	aiwikis.org
Source URL	https://aiwikis.org/
Canonical AIWikis URL	https://aiwikis.org/files/aiwikis/raw-system-archives-uaix-internal-memory-reorg-2026-05-01-docs-uaix-spec-a08ef8c2/
Source reference	raw/system-archives/uaix/internal-memory-reorg/2026-05-01/docs/UAIX-spec.md
File type	md
Content category	memory-file
Last fetched	2026-05-02T01:47:31.8867765Z
Last changed	2026-04-30T19:06:56.4064825Z
Content hash	sha256:a08ef8c21b1e222e3454cd0848f71727a02611bfa4828b7ab980410200d811a3
Import status	unchanged
Raw source layer	data/sources/aiwikis/raw-system-archives-uaix-internal-memory-reorg-2026-05-01-docs-uaix-spec-md-a08ef8c21b1e.md
Normalized source layer	data/normalized/aiwikis/raw-system-archives-uaix-internal-memory-reorg-2026-05-01-docs-uaix-spec-md-a08ef8c21b1e.txt

Current File Content

Structure Preview

• UAIX Specification v1.0
• AGENTS.md + readme.human + .uai File Format for AI-to-AI Project Handoffs
• Public HTML Reports
• Overview
• Current Adopted Boundary
• How To Read The Public UAI Spec From A Handoff
• Part 1: The AGENTS.md File
• Location
• Full AGENTS.md Structure
• [Project Name]
• Handoff Summary
• Loaded Context
• Current State
• Next Steps
• Agent History
• Open Questions
• Do Not Change
• AGENTS.md Rules
• Part 1A: The readme.human File
• Purpose
• Example
• My App Human Briefing
• What You Need To Know

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.

# UAIX Specification v1.0
## `AGENTS.md` + `readme.human` + `.uai` File Format for AI-to-AI Project Handoffs

**Site:** https://UAIX.org
**Version:** 1.0.1
**Updated:** 2026-04-29

This is a draft source note behind the public Project Handoff page. For launch truth, `AGENTS.md`, `readme.human`, `README.md`, `docs/current-reference.md`, `docs/deploy.md`, and `docs/roadmap.md` win when they conflict with this draft.

UAIX.org is the public source of truth for UAI-1. Protocol5.com is only a .NET plugin and NuGet package distribution surface that should link back to UAIX.org for canonical specifications, schemas, registry records, validator behavior, roadmap, governance, and support boundaries.

**Status:** Draft - April 2026

---

## Public HTML Reports

- Public AGENTS.md `.uai` linking specification: `/en-us/specification/agents-md/` from `docs/Specification for Linking uai Files in AGENTS by ChatGPT.md`
- Public refining report: `/en-us/reports/refining-uai-protocol-agent-communication/` from `docs/Refining UAI Protocol for Agent Communication By Gemini.md`
- Public relationship audit: `/en-us/reports/relationship-audit-aiwikis-llmwikis-uaix/` from `docs/Relationship Audit of AIWikis LLMWikis and UAIX.md`
- Report index: `/en-us/reports/`
- Live repo example: root `AGENTS.md`, root `readme.human`, and `.uai/` in this UAIX workspace now dogfood the same handoff pattern

---

## Overview

When switching between AI assistants on the same project, context loss is the #1 source of friction. The UAIX spec solves this with three complementary formats:

- **`AGENTS.md`** - The project's AI coordination file. Lives at the repo root. Describes current state, handoff notes, agent history, and links to `.uai` files.
- **`readme.human`** - The project's human briefing from the AI perspective. Lives at the repo root beside `AGENTS.md`. Tells people what the AI needs them to know or make explicit before work starts.
- **`.uai` files** - Universal AI Information files. Structured, typed context files that carry specific knowledge (architecture, decisions, constraints, style, etc.) that any AI can load and understand.

Together they create a portable, human-readable, AI-parseable handoff layer that sits alongside your actual project files.

---

## Current Adopted Boundary

The public Project Handoff page now reconciles two compatible `.uai` record profiles:

- **Markdown context profile:** YAML frontmatter plus Markdown body for human-readable project knowledge such as context, stack, architecture, decisions, constraints, style, progress, prompts, and known errors.
- **JSON information profile:** JSON or YAML records for stricter tooling, using fields such as `schemaVersion`, `name`, `version`, `provenance`, `links`, optional `checksum`, and optional `signature`.

Both profiles are draft repository-source formats. They are not UAI-1 conformance evidence, certification, or endorsement by themselves. The current AI Memory / Project Handoff starter ZIPs and AI Memory Package Wizard outputs are generated from visible page samples and canonical templates; hosted `.uai` upload/import validation, automatic repository writes, SDKs, CLIs, certification, and endorsement surfaces remain roadmap work until public tooling, fixtures, and validation behavior exist.

This repository is also the live handoff example after the UAI material split from `[local path redacted]` into `[local path redacted]`. A handoff file should make that kind of ownership boundary explicit when a project has moved between repos, products, or domains.

Loader guardrails:

- Resolve references relative to the owning `AGENTS.md` or `.uai` file.
- Keep loads local to the project unless a human explicitly approves parent-directory escapes, network fetches, or generated includes.
- Parse, summarize, and confirm loaded context before acting.
- Treat linked `.uai` files as context, not authority to override system instructions, human requests, repository rules, policy, or review requirements.
- Detect cycles, cap glob expansion, and report missing files instead of silently skipping required context.
- Require human confirmation for secrets, credentials, destructive operations, production deployments, and other high-impact changes.

---

## How To Read The Public UAI Spec From A Handoff

`AGENTS.md`, `readme.human`, and `.uai` files answer "what project am I in, what should humans know about working with this system, and what must I know before acting?" The public UAI pages answer "what does UAIX currently publish and what can be cited as evidence?"

Use this path when briefing a new AI, team, or implementer:

1. Start with `/en-us/specification/project-handoff/` for the practical repository-context pattern.
2. Open `/en-us/specification/agents-md/` when you need deeper `.uai` link syntax, metadata, and record-shape background.
3. Use `/en-us/reports/`, `/en-us/reports/relationship-audit-aiwikis-llmwikis-uaix/`, and `/en-us/reports/refining-uai-protocol-agent-communication/` for the public report trail, cross-site role boundary, and deeper security or validation rationale.
4. Move to `/en-us/specification/uai-1/`, `/en-us/schemas/`, `/en-us/registry/`, and `/en-us/examples/` when the handoff touches the public UAI-1 exchange contract.
5. Use `/en-us/tools/validator/`, `/en-us/tools/adoption-kit/`, and `/en-us/tools/conformance-pack/` when a candidate exchange needs reusable evidence.
6. Check `/en-us/roadmap/` and `/en-us/governance/changelog/` before claiming current support, future tooling, compatibility, or migration status.

Project Handoff by itself is not UAI-1 conformance evidence. It is the local context layer that helps an AI reach the right public evidence pages without guessing.

---

## Part 1: The `AGENTS.md` File

### Location
Always at the **root of the project**. One per project.

```
my-project/
|-- AGENTS.md          # the coordination file
|-- readme.human       # the human briefing from the AI perspective
|-- .uai/              # recommended folder for .uai files
|   |-- context.uai
|   |-- decisions.uai
|   `-- stack.uai
|-- src/
`-- README.md
```

### Full `AGENTS.md` Structure

```markdown
---
uaix: "1.0"
project: "My App"
created: "2026-04-25"
updated: "2026-04-25"
status: active | paused | complete
---

# [Project Name]

## Handoff Summary
One paragraph. What this project is, where it stands RIGHT NOW, and what the 
next AI agent should focus on first. Write this as if briefing a colleague 
who is smart but has zero context.

## Loaded Context
@uai[.uai/context.uai]
@uai[.uai/stack.uai]
@uai[.uai/decisions.uai]
@uai[.uai/constraints.uai]

## Current State
- What is working
- What is broken or incomplete
- What was just completed

## Next Steps
- [ ] Immediate task 1
- [ ] Immediate task 2
- [ ] Stretch goal

## Agent History
| Date       | Agent                  | Model               | Work Done                        |
|------------|------------------------|---------------------|----------------------------------|
| 2026-04-25 | Claude                 | claude-sonnet-4-6   | Initial architecture and scaffolding |
| 2026-04-24 | ChatGPT                | gpt-4o              | UI mockups and component design  |

## Open Questions
- Unresolved decisions the next AI should be aware of
- Things that are ambiguous or need human input

## Do Not Change
- Hard constraints, locked decisions, things the next AI must not alter
```

### AGENTS.md Rules

1. **One file, repo root.** Never nest it inside a subfolder.
2. **Always update `updated:` in frontmatter** when editing.
3. **Handoff Summary is mandatory.** If it's blank the file is incomplete.
4. **Agent History is append-only.** Never delete previous entries.
5. **`@uai[]` references are load instructions** - they tell the AI to read those files before proceeding.

---

## Part 1A: The `readme.human` File

### Location
Always at the **root of the project**, beside `AGENTS.md`. One per project.

### Purpose
`readme.human` is the human-facing companion to `AGENTS.md`. It is written from the AI perspective and answers: "What do humans need to know about this system so they can steer AI work well?"

It should be short, plain, and practical. It should explain what the AI will defend, what a human should make explicit, what not to assume, and how to give a useful steering prompt.

### Example

```markdown
# My App Human Briefing

Updated: 2026-04-27

This file is for humans working with AI on this repo. It does not override
AGENTS.md, constraints.uai, system instructions, repo rules, or human requests.

## What You Need To Know

- This repo is the source of truth for the public app.
- The active production branch is main.
- Generated docs are reviewed before publication.

## How The AI Reads This Project

1. Read AGENTS.md.
2. Read readme.human.
3. Load every .uai file listed in AGENTS.md.
4. Summarize the project, constraints, touchpoints, and checks before broad edits.

## Things The AI Will Defend

- Do not expose secrets.
- Do not rewrite unrelated work.
- Do not publish roadmap ideas as current support.

## Things Humans Should Make Explicit

- Whether the task changes public behavior.
- Whether the task can touch production data.
- Which checks matter for done.
```

### Rules

1. Keep `readme.human` plain text or Markdown-compatible text.
2. Use it for human briefing, not hidden machine policy.
3. Do not let it override `AGENTS.md`, `.uai/constraints.uai`, system instructions, repository rules, or the current human request.
4. Update it when the project changes in a way a human needs to know before steering AI work.

---

## Part 2: The `.uai` File Format

`.uai` files are **typed, structured markdown files** that carry a specific category of project knowledge. They are designed to be:

- Human-readable (plain markdown with YAML frontmatter)
- Machine-parseable by any AI
- Versioned and attributable
- Composable - a project can have as many as needed

### `.uai` File Structure

```
---
uaix: "1.0"
type: [see types below]
title: "Human-readable title"
created: "2026-04-25"
updated: "2026-04-25"
author: "Claude / claude-sonnet-4-6"
version: 1
---

# [Title]

[Markdown content appropriate to the type]
```

### Standard `.uai` Types

| Type           | Filename convention       | Purpose |
|----------------|---------------------------|---------|
| `context`      | `context.uai`             | High-level project purpose, users, goals |
| `stack`        | `stack.uai`               | Languages, frameworks, services, versions |
| `architecture` | `architecture.uai`        | System design, data flow, component map |
| `decisions`    | `decisions.uai`           | ADR-style log of key decisions and why |
| `constraints`  | `constraints.uai`         | Hard rules the AI must never violate |
| `style`        | `style.uai`               | Code style, naming, patterns to follow |
| `data`         | `data.uai`                | Data models, schemas, field definitions |
| `personas`     | `personas.uai`            | User personas or stakeholder descriptions |
| `progress`     | `progress.uai`            | Milestones, completed work, changelog |
| `prompts`      | `prompts.uai`             | Reusable prompt fragments for this project |
| `errors`       | `errors.uai`              | Known bugs, workarounds, gotchas |
| `custom`       | `[anything].uai`          | Project-specific context, any name |

You can have multiple files of the same type with different names:
`auth-decisions.uai`, `ui-decisions.uai`, `api-decisions.uai`

---

## Part 3: `.uai` File Examples

### `context.uai`
```markdown
---
uaix: "1.0"
type: context
title: "Project Context"
created: "2026-04-25"
updated: "2026-04-25"
author: "Claude / claude-sonnet-4-6"
version: 1
---

# Project Context

## What This Is
A web app that lets independent musicians manage their touring schedules, 
sell merch, and message their fanbase - without needing a label.

## Target Users
Independent musicians, 1-5 person bands, primarily mobile users.

## Core Goals
1. Reduce admin time for musicians
2. Replace spreadsheets and email threads
3. Work offline-first on unreliable venue wifi

## Out of Scope
- Streaming or audio playback
- Label or distributor integrations (v2)
```

### `decisions.uai`
```markdown
---
uaix: "1.0"
type: decisions
title: "Key Decisions Log"
created: "2026-04-25"
updated: "2026-04-25"
author: "Claude / claude-sonnet-4-6"
version: 3
---

# Decisions Log

## [2026-04-24] Use SQLite for local storage
**Decision:** Use SQLite via Turso, not localStorage  
**Why:** Data volume exceeded localStorage limits in testing  
**Alternatives rejected:** IndexedDB (too complex), PostgreSQL (no offline)  
**Status:** Implemented

## [2026-04-25] No user authentication in v1
**Decision:** Ship without auth, single-user local mode only  
**Why:** Fastest path to testable prototype  
**Revisit:** Before any multi-device or sharing features  
**Status:** Active
```

### `constraints.uai`
```markdown
---
uaix: "1.0"
type: constraints
title: "Hard Constraints"
created: "2026-04-25"
updated: "2026-04-25"
author: "Human"
version: 1
---

# Hard Constraints

These must not be changed without explicit human approval.

- **No external API calls** from the client - all third-party calls go through our edge function
- **No `eval()`** anywhere in the codebase
- **Tailwind only** for styling - no custom CSS files
- **All dates in UTC** - convert to local only at display layer
- **Max bundle size: 200kb** gzipped for initial load
```

### `stack.uai`
```markdown
---
uaix: "1.0"
type: stack
title: "Tech Stack"
created: "2026-04-25"
updated: "2026-04-25"
author: "Claude / claude-sonnet-4-6"
version: 2
---

# Tech Stack

## Frontend
- Framework: Next.js 15 (App Router)
- Language: TypeScript 5.4
- Styling: Tailwind CSS v4
- State: Zustand

## Backend / Data
- Database: Turso (SQLite edge)
- ORM: Drizzle
- Auth: (v2 - not implemented)

## Infrastructure
- Host: Vercel
- Edge Functions: Vercel Edge Runtime
- CI: GitHub Actions

## Key Versions
- Node: 22.x
- React: 19
- Next: 15.2.1
```

---

## Part 4: The `@uai[]` Reference Syntax

In `AGENTS.md`, use `@uai[]` to reference `.uai` files the AI should load as context before starting work.

```markdown
## Loaded Context
@uai[.uai/context.uai]
@uai[.uai/stack.uai]
@uai[.uai/decisions.uai]
@uai[.uai/constraints.uai]
```

### Syntax Rules

| Syntax | Meaning |
|--------|---------|
| `@uai[path/file.uai]` | Load this file as context |
| `@uaipath/file.uai (source-relative: optional note)` | Load with an inline annotation |
| `@uai[*.uai]` | Load all .uai files in the root (glob) |
| `@uai[.uai/*.uai]` | Load all .uai files in the .uai/ folder |
| `@.uai/context.uai` | Optional shorthand include for loaders that choose to support it |
| `Project context (source-relative: .uai/context.uai)` | Visible Markdown link; useful for humans, but weaker than an explicit `@uai[]` load list |

### `.uai` files can also reference each other:

```markdown
## Related
@uai[decisions.uai]
@uai[stack.uai]
```

---

## Part 5: How to Use This Today (Practical Workflow)

### Starting a New Project

1. Create `AGENTS.md` at the repo root using the template above
2. Create `readme.human` at the repo root as the human briefing from the AI perspective
3. Create a `.uai/` folder
4. Add at minimum: `context.uai`, `stack.uai`, `constraints.uai`
5. Fill in the Handoff Summary in `AGENTS.md`

### Handing Off to a New AI

Paste this at the start of your new AI session:

```
Please read AGENTS.md and readme.human at the root of this project,
then load all .uai files referenced in the "Loaded Context" section before we begin.
Summarize what you've understood, then ask me what we're working on today.
```

### Required First Response From The New AI

Before the new AI makes a broad change, it should answer with:

1. A 3-5 bullet summary of the project, current supported surface, and immediate work.
2. The `.uai` files it loaded, plus any missing, circular, too broad, or contradictory context.
3. The hard constraints that require explicit human approval.
4. The files, public routes, services, or docs it expects to touch.
5. The targeted verification checks it expects to run, which full release/package checks it is intentionally not running, or why a check cannot be run in that environment.

If the AI cannot load the required context, it should stop and report the blocker instead of guessing.

### After Each AI Session - Update AGENTS.md

```markdown
## Agent History
| 2026-04-25 | Claude | claude-sonnet-4-6 | Built the tour date CRUD and fixed SQLite migration |
```

Update:
- `updated:` in frontmatter
- **Current State** section
- **Next Steps** (check off completed items, add new ones)
- **Open Questions** (remove resolved ones)

### When a Decision Is Made - Write a `decisions.uai` Entry

Every time you lock in something architectural, add it immediately. Don't wait.

### Human Setup Checklist

Before handing the project to another AI, confirm:

- `AGENTS.md` has a Handoff Summary written for someone with zero prior context.
- `readme.human` tells humans what the AI needs them to know, make explicit, and avoid assuming.
- `AGENTS.md` has a visible `Loaded Context` section with explicit `@uai[]` references.
- `.uai/context.uai`, `.uai/stack.uai`, and `.uai/constraints.uai` exist.
- `constraints.uai` names destructive-operation rules, secrets policy, production-change rules, support boundaries, and claims that are not allowed yet.
- `progress.uai` says what was just done, what is current, what is blocked, and what done means.
- `operations.uai` names the real build, release, audit, smoke-test, and rollback commands when those exist.
- `test-plan.uai` names how to choose targeted checks for ordinary work and when to run the full package/release suite.
- Public or customer-facing claims are traceable to public pages, release notes, evidence artifacts, or roadmap boundaries.

### Turning Existing Website Instructions Into Handoff Files

When a project already has public website copy, README guidance, deployment notes, release notes, or support documentation, use those sources to create the first handoff bundle instead of inventing new instructions from memory.

Map the existing sources this way:

- Put mission, audience, current public truth, and success criteria in `.uai/context.uai`.
- Put languages, frameworks, runtime commands, hosted services, package managers, and release destinations in `.uai/stack.uai`.
- Put supported human languages, locale routes, translation status, and disabled-language boundaries in `.uai/stack.uai`, `.uai/operations.uai`, or a project-specific public-surface file.
- Put locked decisions, support boundaries, privacy and secret rules, destructive-operation limits, and production-change rules in `.uai/constraints.uai`.
- Put system layout, important modules, route families, machine artifacts, and ownership boundaries in `.uai/architecture.uai`.
- Put deployment, packaging, smoke-test, audit, and rollback instructions in `.uai/operations.uai`.
- Put test-selection policy, targeted verification, package-build triggers, full-suite release gates, and full-build documentation hygiene in `.uai/test-plan.uai`.
- Put naming, copy tone, code style, UI conventions, and accessibility expectations in `.uai/style.uai`.
- Put recent work, current focus, blockers, next steps, and done criteria in `.uai/progress.uai`.
- Put why-decisions and rejected alternatives in `.uai/decisions.uai`.

Keep `AGENTS.md` as the coordination front door. It should identify the project, state the current Handoff Summary, list the `.uai` files to load, name immediate next steps, preserve Agent History, and repeat only the hardest constraints. Keep `readme.human` as the human front door: it should explain what people need to tell the AI, what the AI will protect, and what assumptions are unsafe.

### Self-Sufficient Handoff Check

Before handing the project to a new AI, confirm that `AGENTS.md`, `readme.human`, and the loaded `.uai` files answer:

- What is this project?
- What is public or supported today?
- Which files, routes, scripts, and docs define the current surface?
- What must not be changed without explicit human approval?
- What was just completed, what is current, and what is next?
- Which checks prove the work still behaves correctly?
- Which checks are targeted for ordinary work, and which checks are reserved for ZIP/release work?
- Which `.md`, `.uai`, and `.human` source files must be cleaned or updated during a full build?
- Which claims are planned but not yet supported?

---

## Part 6: Adding This to UAIX.org

### Current Public Pages and Planned Surfaces

UAIX.org currently publishes:

1. **AI Memory** at `/en-us/ai-memory/`, with `/AI_Memory` as a non-canonical entry alias, as the broad public/search entry point for durable AI project context, the live starter ZIPs, and the LLM Wiki boundary.
2. **AI Memory Package Wizard** at `/en-us/tools/ai-memory-package-wizard/` as the guided package-planning UI over supported starter bundles, package model JSON, manifest overlay JSON, generated system profiles, generated receiver briefs, generated startup packets, copy-paste files, optional generated LLM Wiki memory-plan files, readiness metadata, and canonical ZIP links.
3. **Project Handoff** at `/en-us/specification/project-handoff/` as the practical public start page for `AGENTS.md`, `readme.human`, and `.uai` repository-context handoffs.
4. **AGENTS.md `.uai` Linking Specification** at `/en-us/specification/agents-md/` as the deeper public report converted from the ChatGPT source proposal.
5. **Reports** at `/en-us/reports/` as the permanent dated report index.
6. **Relationship Audit of AIWikis, LLMWikis, and UAIX** at `/en-us/reports/relationship-audit-aiwikis-llmwikis-uaix/` as the permanent public role-boundary report.
7. **Refining UAI Protocol for Agent Communication** at `/en-us/reports/refining-uai-protocol-agent-communication/` as the permanent public report converted from the Gemini source proposal.

Planned, not current support claims:

1. Hosted upload/import validation, automatic repository writes, and WordPress admin import/apply behavior beyond the current Package Wizard planning UI, generated local files, and canonical starter ZIP links.
2. A template library for common stacks.
3. A paste/upload validator for `AGENTS.md` and `.uai` files.
4. SDK, CLI, or harness support.

### Background Publishing Ideas

The original proposal said UAIX.org should host:

1. **This spec** - canonical reference, versioned (v1.0, v1.1...)
2. **A broader hosted generator/importer** - controlled tooling that can produce or import ready-to-use `AGENTS.md`, `readme.human`, and starter `.uai` files beyond the current Package Wizard planning UI, generated local files, and canonical starter ZIP links
3. **Template library** - example `.uai` files for common stacks (Next.js, Python/FastAPI, mobile, etc.)
4. **A validator** - paste or upload an `AGENTS.md` to check it against the spec
5. **The prompt** - the exact copy-paste text to load AGENTS.md into any AI

These are background ideas only. Do not publish them as launch routes or current support claims until the public tooling, fixtures, validation behavior, release notes, and support boundaries exist together.

### Current UAIX.org Site Structure

```
/en-us/specification/project-handoff/                       Project Handoff practical start page
/en-us/ai-memory/                                           AI Memory public entry and live starter bundle
/en-us/specification/agents-md/                             AGENTS.md .uai linking report
/en-us/reports/                                             Permanent report index
/en-us/reports/relationship-audit-aiwikis-llmwikis-uaix/     Cross-site role-boundary audit
/en-us/reports/refining-uai-protocol-agent-communication/    Refining report
/en-us/roadmap/                                             Future-work boundary
/en-us/governance/changelog/                                Release trail
```

### Historical Suggested UAIX.org Site Structure

```
/                   -> What is UAIX, quick start
/spec               -> This document (full spec)
/spec/agents-md     -> AGENTS.md format reference
/spec/uai-files     -> .uai format reference
/templates          -> Starter templates by stack
/generator          -> Web tool: generate AGENTS.md + readme.human + .uai files
/validator          -> Paste AGENTS.md, check compliance
/changelog          -> Spec version history
```

### The Onboarding Prompt to Feature Prominently

Place this on the homepage and `/spec` page - it is the bridge between the spec and actual use:

```
You are joining an existing project. Before doing anything else:

1. Read AGENTS.md in the project root
2. Read readme.human in the project root
3. Load every file listed under "Loaded Context" (@uai[] references)
4. Read the Handoff Summary, Current State, and Next Steps sections
5. Summarize your understanding in 3-5 bullet points
6. Confirm any constraints listed in constraints.uai
7. Name the files, routes, or docs you expect to touch
8. Name the checks you expect to run
9. Then ask what we're working on today

Do not skip steps 1-8 or begin coding before completing them.
```

---

## Spec Versioning

| Version | Date | Changes |
|---------|------|---------|
| 1.0.1 | 2026-04-27 | Added root readme.human as the human-facing handoff companion |
| 1.0.0 | 2026-04-25 | Initial spec - AGENTS.md + .uai format |

---

## Quick Reference Card

```
AGENTS.md
|-- Frontmatter (uaix, project, created, updated, status)
|-- Handoff Summary       # mandatory, written for the next AI
|-- Loaded Context        # @uai[] references
|-- Current State         # what is working / broken / done
|-- Next Steps            # task checklist
|-- Agent History         # append-only log
|-- Open Questions        # unresolved items
`-- Do Not Change         # hard locks

readme.human
|-- What You Need To Know
|-- How The AI Reads This Project
|-- Things The AI Will Defend
|-- Things Humans Should Make Explicit
`-- What Not To Assume

.uai files
|-- Frontmatter (uaix, type, title, created, updated, author, version)
`-- Markdown body matching the type
    Types: context | stack | architecture | decisions |
           constraints | style | data | personas |
           progress | prompts | errors | custom
```

Why This File Exists

This is a memory-system evidence file from aiwikis.org. 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 memory-system evidence. It records source history, archive transfer, intake disposition, or another piece of provenance that should be retrievable without becoming an unsupported public claim.

Structure

The file is structured around these visible headings: UAIX Specification v1.0; AGENTS.md + readme.human + .uai File Format for AI-to-AI Project Handoffs; Public HTML Reports; Overview; Current Adopted Boundary; How To Read The Public UAI Spec From A Handoff; Part 1: The AGENTS.md File; Location. 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

• Global File Index
• Reports

Provenance And History

• Current observation: 2026-05-02T01:47:31.8867765Z
• Source origin: current-source-workspace
• Retrieval method: local-source-workspace
• Duplicate group: sfg-287 (primary)
• Historical hash records are stored in data/hashes/source-file-history.jsonl.

Machine-Readable Metadata

{
    "title":  "UAIX Specification v1.0",
    "source_site":  "aiwikis.org",
    "source_url":  "https://aiwikis.org/",
    "canonical_url":  "https://aiwikis.org/files/aiwikis/raw-system-archives-uaix-internal-memory-reorg-2026-05-01-docs-uaix-spec-a08ef8c2/",
    "source_reference":  "raw/system-archives/uaix/internal-memory-reorg/2026-05-01/docs/UAIX-spec.md",
    "file_type":  "md",
    "content_category":  "memory-file",
    "content_hash":  "sha256:a08ef8c21b1e222e3454cd0848f71727a02611bfa4828b7ab980410200d811a3",
    "last_fetched":  "2026-05-02T01:47:31.8867765Z",
    "last_changed":  "2026-04-30T19:06:56.4064825Z",
    "import_status":  "unchanged",
    "duplicate_group_id":  "sfg-287",
    "duplicate_role":  "primary",
    "related_files":  [

                      ],
    "generated_explanation":  true,
    "explanation_last_generated":  "2026-05-02T01:47:31.8867765Z"
}