UAIX Alignment Review of the .uaix Draft

Full report

On this page

Executive assessment

Your instinct about avoiding “recommended” and “optional” matches the way the current UAIX required-file guidance is structured. The stronger UAIX pattern is not just “make more things required”; it is a closed required-set model that classifies files as universal required, profile-required, content-triggered required, configuration-specific required, or out of scope. The public .uai file guidance and the current wizard both use that family/profile/capability model rather than a flat “required vs optional” split.

Because of that, the biggest problem in the draft is broader than wording. The draft turns UAIX into a small fixed container with a thin minimum file list, while current UAIX guidance treats package contents as a declared, scope-sensitive file set derived from bundle family, code-bearing status, long-memory configuration, file-handoff status, and other content facts. In its current form, the draft does not follow that model.

A few parts of the draft do align with current UAIX direction: the local-first ZIP packaging idea, the insistence that a package be transferable without hosted services, and the statement that memory is not authority all fit the public UAIX posture. UAIX repeatedly describes AI Memory as a local, file-based, reviewable packet, and the Memory Firewall explicitly says imported memory is not permission to execute.

File-set and package-family mismatches

The single largest structural mismatch is the minimum file set. Your draft says a minimal .uaix package only needs a manifest plus .uai/startup-packet.uai, .uai/system-profile.uai, and .uai/receiver-brief.uai. Current UAIX guidance says every launch-baseline memory or handoff package requires .uai/memory-maintenance.uai, .uai/identity.uai, .uai/world-context.uai, .uai/totem.uai, .uai/taboo.uai, .uai/talisman.uai, and .uai/short-term-memory.uai. Those are not extras; they are the universal baseline.

That means your current “Recommended Files” section is misaligned in a deeper way than just vocabulary. In UAIX, totem.uai, taboo.uai, and talisman.uai are default active instruction anchors that agents must read and obey, and they must not be mutated except with exact human artifact-and-operation authorization. In your draft, those anchors are portrayed as files that “may be included” and were placed in the non-required bucket. That is a direct conflict with current public UAIX guidance.

The draft also under-specifies Project Handoff and code-bearing scopes. The UAIX file guide marks .uai/startup-packet.uai, .uai/system-profile.uai, and .uai/receiver-brief.uai as Required for Project Handoff packages, while project/developer and code-bearing assistant packages also require .uai/coding-standards.uai, .uai/architecture.uai, and .uai/next-recursive-prompt.uai. Your draft mentions some of these files only as non-required material, instead of making them required when the package declares code, automation, executable workflows, or code-like artifacts.

There is another important omission: the public wizard now treats non-project assistant packages as their own declared family. Those packages use assistant-specific files such as assistant profile, relationship boundary, privacy boundary, user preferences, and memory-update rules. Since your own examples include HelpfulAssistant.uaix, PlaywrightExpert.uaix, and ShakespeareNovelist.uaix, the draft is implicitly describing assistant-style packages, but it does not model their assistant-family required files at all.

The wizard also goes beyond family-based requirements and uses content-triggered package facts. Current UAIX package planning can make files required based on whether a package declares tool permissions, contact memory, calendar and scheduling memory, communication-style memory, tasks and commitments, routines and preferences, safety/support boundary memory, source notes, or public-facing behavior. Your draft has no mechanism for those triggers, so it cannot reproduce the current UAIX required-set logic for real assistant or office-style packages.

Long-memory and archive model mismatches

The draft’s long-memory model does not follow current UAIX layering. Public UAIX guidance treats LLM Wiki as a deep-memory configuration path, not a baseline part of every package. When a project uses that path, .uai/long-term-memory.uai becomes the active pointer file required for the long-memory configuration, but the wiki itself remains background memory until reviewed and promoted into accepted package surfaces. Your draft instead makes .uai/wiki/docs/ the default expected long-term memory location inside the package and talks about it almost like a built-in source-of-truth layer. That blurs UAIX’s hot/cold boundary.

Current UAIX guidance is much more specific about what a long-memory path must name. When a package is shaped for an LLM Wiki, UAIX expects the package to record the approved wiki root, index, log, steward, promotion targets, evidence log, and source boundary. The guidance also says a new wiki root normally starts with a read-only raw/ layer plus reviewed wiki/index.md and wiki/log.md. Your draft’s portableWikiRoots and longTermMemory.defaultPath fields are too thin to carry that UAIX routing model.

The same issue appears in the shared-wiki section. UAIX says that when multiple source sites share one long-memory layer, records must preserve source path, destination path, disposition, checksum, review state, promotion status, and owning site namespace, and shared roots must keep ownership boundaries distinct instead of flattening all source material into one generic folder. A simple "shared wiki docs folder used by multiple profiles" is not enough to match that guidance.

Your archive/content-type rules are also too restrictive for current UAIX practice. The draft says recommended allowed extensions are .uai, .json, .md, and .txt, but current UAIX file-handoff guidance explicitly operates on PDFs, screenshots, exports, ZIPs, spreadsheets, and other loose files as reviewable source/input material. That matters because your own draft describes archives/ as “raw or source evidence.” If archives are supposed to preserve real source evidence, then a text-only allowlist does not match the way UAIX currently treats intake and preserved source material.

Security, authority, and import boundary gaps

The security model in the draft is directionally right, but it is still underpowered compared with current UAIX guidance. The UAIX Memory Firewall says imported packets are quarantined public data until validation and local policy accept them; a valid packet is not trusted memory, safe code, or permission to execute. It also says startup packets must be schema-validated before adoption, and ambiguous authority, missing provenance, missing integrity, or conflicting memory must produce no-op plus human review. Your draft talks about rejecting bad ZIPs, but it does not establish the full quarantine-first promotion model.

Related to that, the draft never makes room for the UAIX-required no-op model. Public schemas require no-op-related fields repeatedly: the startup packet requires no_op_triggers and validation_targets, the receiver brief requires no_op_triggers and escalation_triggers, the memory-firewall policy requires quarantine_default, adoption_requirements, blocked_requests, and human_review_required, and the authority boundary profile requires not_authorized_for and no_op_triggers. Your draft’s manifest and import rules do not carry those concepts, which means it cannot express current UAIX boundary behavior.

The anchor-mutation wording is also too loose. UAIX does not say “explicit user approval” in a generic sense; the current anchor guidance uses the stricter formula exact human artifact-and-operation authorization. That difference matters because UAIX’s Talisman guidance is designed specifically to block vague, inferred, or conversationally widened permission when totem.uai, taboo.uai, or talisman.uai are in play.

Your capabilities object is another mismatch. Current UAIX keeps runtime execution, tool calls, approvals, live traces, and session memory in the harness/control layer, while UAI/UAIX preserves the reviewed record and boundary declarations. That means booleans like mayEnableNetwork or mayEnableTools are fine as descriptive metadata, but they are not the strongest UAIX mechanism. The public UAIX pattern is closer to authority-boundary records, blocked actions, no-op triggers, required human approval, and evidence requirements than to a flat power switch inside a package manifest.

Packaging and support-claim mismatches

The manifest model needs rework if the goal is alignment with the current public record. UAIX clearly does use manifests, but the current public packaging surface emphasizes a generated manifest inside the ZIP, a manifest overlay JSON, and machine-readable exports such as .uai/exports/manifest.json. The AI Memory read path also expects the agent to read the manifest and front-door files before acting, and the wizard’s session-start guidance points directly to .uai/exports/manifest.json. Your draft invents a new mandatory .uai/manifest.uaix.json path and a schema URL without tying it back to the current public schema/registry/validator chain. That makes it feel like a new proposal rather than a faithful restatement of current UAIX packaging.

If the draft is supposed to cover project or repository handoff, it also omits the current UAIX front door. Project Handoff uses AGENTS.md as the durable front door and readme.human as the human briefing surface, and its load path starts there before typed .uai records are read. The draft never says whether .uaix is assistant-only desktop packaging or a full Project Handoff carrier. If it is the latter, the omission is a real mismatch. If it is the former, that narrowing needs to be stated explicitly.

The Desktop Load Model section also mixes client-runtime behavior into what looks like a UAIX core spec. Public UAIX guidance consistently separates runtime concerns from portable memory/evidence. Harnesses own session execution, tool calls, approvals, retries, and live runtime memory; UAIX keeps the reviewed handoff and evidence layer. So OS-specific expansion paths, session JSON layouts, and multi-instance runtime rules are best treated as implementation guidance for a client, not as core UAIX semantic requirements.

Finally, the draft should be more explicit about proposal status. The public UAIX record warns that language about generators, upload validators, SDKs, CLIs, certification, endorsement, and similar packaging/distribution surfaces is proposal or roadmap material unless the public roadmap, changelog, and tooling evidence say otherwise. Current public UAIX pages do publish browser-generated ZIP packages and canonical starter ZIPs, but they do not present a mature public .uaix extension standard in the way this draft implies.

Rewrite priorities

If you want this draft to read like current UAIX guidance rather than a parallel packaging idea, these are the highest-priority changes:

• Replace the current Required Files section with a Universal Required Files section that includes .uai/memory-maintenance.uai, .uai/identity.uai, .uai/world-context.uai, .uai/totem.uai, .uai/taboo.uai, .uai/talisman.uai, and .uai/short-term-memory.uai. Then move startup/system/receiver into a separate Required for Project Handoff packages section unless .uaix is explicitly defined as a special desktop startup carrier.

• Replace all “Recommended” and “Optional” groupings with UAIX-style scopes such as Required for Project Handoff, Required for Long-Term Memory configuration, Required for Agent File Handoff, Required for code-bearing packages, Required for non-project assistant packages, and Out of scope. That is much closer to the current UAIX grammar than a flat recommended/optional bucket.

• Move totem.uai, taboo.uai, and talisman.uai out of the discretionary set and describe them as default active instruction anchors. Replace “explicit user approval” with exact human artifact-and-operation authorization anywhere anchor mutation is discussed.

• Add the missing family/content triggers for assistant-style packages. At minimum, the spec should account for assistant profile, relationship boundary, privacy boundary, user preferences, memory-update rules, and the package facts that make additional files required, such as tool permissions, contact memory, calendar memory, communication-style memory, tasks/commitments, routines/preferences, safety/support boundaries, source notes, and public-facing behavior.

• Rework long memory so that the baseline package stays under .uai/, .uai/archives/, and .uai/exports/, while wiki memory is only required for LLM Wiki configuration and is carried through .uai/long-term-memory.uai. The long-memory section should name root, index, log, steward, promotion targets, evidence log, and source boundary, and it should say that wiki memory stays background until promoted.

• Relax the file-type rules for archives/source evidence. Keep active typed memory mostly text-first if you want, but do not make raw/source evidence text-only when current UAIX file-handoff practice explicitly works with PDFs, screenshots, exports, ZIPs, and spreadsheet-like evidence.

• Add a full quarantine/provenance/no-op/human-review import section. It should say imported packages start quarantined, startup packets must validate before adoption, receiver briefs must carry read order and escalation/no-op behavior, and boundary conflicts fail closed through no-op plus human review.

• Treat the .uaix extension, manifest path, expansion directories, and per-session JSON records as proposal or implementation guidance unless and until you publish them through the same schema/registry/changelog path the current public UAIX record uses. As written, that part of the draft is ahead of the currently documented public packaging surface.

The strongest single rewrite is this: instead of defining .uaix as a tiny fixed package with a few optional extras, define it as a container for the current UAIX closed required file set, where the effective contents are derived from the declared package family, trust boundary, code-bearing status, long-memory configuration, file-handoff configuration, and content-triggered package facts. That would bring the draft much closer to the way UAIX currently organizes memory packages in public.