On the ground
the System stands upon.
This document governs the boundary between the portable System and the local ground it occupies but does not own.
The AI OS is portable; the ground beneath it is not. Where the System ends and the working surface begins is a line that must be drawn plainly, lest the most portable content be chained to the least.
These Articles establish the working surface: the documented hierarchy that hosts the System, holds its working content, and resolves to real paths at runtime, while never travelling as part of the System itself.
Of the portable System and the standing ground.
The System shall be portable, and the working surface shall be local.
The three components of the System: the Canon, the Harness, and the Vault, are versioned repositories that may be cloned to any machine. They live within a working surface: a documented folder hierarchy that hosts the System, the working content it operates upon, its caches, its logs, its coordination state, its binary media, and the clones of other corpora its agents ground upon.
The working surface is local. The pattern is portable. The System travels; the working surface stays.
Of the reason the boundary is kept.
No working content shall be defined as part of the System.
Were the System to include the working surface, portability would demand the cloning of every draft, every cache, and every log of every hand that worked it. This is not the design.
By the keeping of this boundary, fresh installs stay cheap: a new machine clones three repositories and receives a full methodology, configuration, and state. Privacy gradients hold, for the Canon may be near to public, the Vault is private decision-history, and the working surface holds the most ephemeral material; to mix them would lock the most portable content behind the least. And the System stays forkable, that another hand or another agent may adopt the pattern without inheriting the original's working content.
Of the standard categories.
Every working surface shall hold folders matching the established roles.
The roles are these: persistent hosting, where the components clone and are tracked; scratch, session-scoped and trashed at session end; analysis, saved until promoted or pruned; caches, regeneratable and safe to wipe; logs, append-only with periodic rotation; coordination state, machine-local journals and breadcrumbs that survive past session end until consumed; binary media, kept outside the Vault for size; and workflow corpora, optional clones bootstrapped per role.
The names and exact paths shall be particular to each hand. The categories are the portable contract. A skill, an agent, or a hook shall reference a category by its role and not by a hardcoded path, save where a hot path makes indirection wasteful; such a path shall be lifted to category-level when it appears in three or more skills.
Of the spec layer.
Each install shall document its conventions in a CLAUDE.md at the root of its working surface.
This spec file names the specific paths chosen for each category, defines the hygiene rules per category, and cross-references the System components by their on-disk location. Claude Code loads it at the start of every session in that directory.
This file shall be local-only and shall never travel in the Canon. The pattern travels in this document; the specifics stay in the user's CLAUDE.md. The spec layer is what lets skills and agents reference categories abstractly while resolving to real paths at runtime.
Of the three classes of reference.
No canonical surface shall reference free-floating content that dangles on a fresh install.
References from the System into the working surface fall into three classes. Folder conventions, which name a category, are portable, for the folder is created on demand per the local spec. Cross-org repo paths, which name a workflow corpus the hand is expected to clone, are semi-portable, working where the clone exists and surfacing cleanly as a missing prerequisite where it does not. Free-floating content, which names a specific file tracked in no repository, is not portable, for the file will dangle on a fresh install.
The third class is the failure mode the System guards against. When a canonical surface would reference free-floating content, that content shall be lifted into the Vault first, where it becomes canonical, and the surface shall reference the now-portable Vault path. This split is enforced by the layered defence stack and surfaced by the doc-coverage and portability-drift SessionStart hooks.
Of where this document sits.
The System, its canonical material, and its working surface shall stand as three concentric layers.
The architecture document names the three components and their lifecycles. The canonical-sources document inventories the canonical material inside the System. The canonical-truth-derivation document holds the discipline that keeps content authoritative and derived views in sync. This document governs the working surface outside the System and the contract by which the System operates upon it.
Each layer has its own lifecycle, its own privacy gradient, and its own portability guarantee. The line between them is not a convenience; it is the design.
These Articles may be amended in the open, as a charter shows its revisions.
The cursor waits for the next hand.