docs(P01): complete core-foundation phase

---ci---
project: atelier
phase: 0
milestone: v0.1
status: complete
phase_role: pre_execution
ship:
  tag: v0.0.0
  merge: phase/00-pre-execution -> milestone/v0.1-atelier
  release: https://git.cloudinit.dev/cloudinit-bot/atelier/releases/tag/v0.0.0
---/ci---

Config owner corrected: coreci -> cloudinit-bot (actual token owner). Phase 0 complete: 10 domain first-principles + matrix + MANIFEST + uiux docs shipped as v0.0.0.

.ciagent/CHECKPOINT.json

@@ -1,8 +1,8 @@
 {
   "phase": 0,
-  "stage": "plan",
+  "stage": "complete",
   "milestone": "v0.1",
   "phase_role": "pre_execution",
   "attempts": 0,
-  "updated_at": "2026-08-05T00:03:00Z"
+  "updated_at": "2026-08-05T00:04:00Z"
 }

.ciagent/config.json

@@ -53,13 +53,13 @@
   "release": {
     "forge": "gitea",
     "base_url": "https://git.cloudinit.dev",
-    "owner": "coreci",
+    "owner": "cloudinit-bot",
     "repo": "atelier"
   },
   "gitea": {
     "base_url": "https://git.cloudinit.dev",
     "api_token_env": "GITEA_API_TOKEN",
-    "owner": "coreci",
+    "owner": "cloudinit-bot",
     "repo": "atelier"
   },
   "ship": {

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atelier contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,90 @@
+# Atelier
+
+A first-principles, docs-as-code engineering framework for AI agents and humans.
+
+## What This Is
+
+Atelier is a hierarchical document tree of engineering principles. Eight universal **core principles** (C1–C8) govern eleven **domains** (API, Security, Data, Testing, Performance, Observability, Errors, Documentation, Concurrency, DevOps, UI/UX), each with ten derived principles (P1–P10). A **principles matrix** maps every domain rule back to the core rule it derives from, making conflict resolution deterministic.
+
+This is not a style guide. This is not a linter. This is a principle hierarchy with cross-references, consumed by AI agents as pre-completion guidance and by humans as engineering canon.
+
+## Who It's For
+
+- **AI agents** — read `core/` then the relevant `domains/` before completing a coding task. Run `review/agent-checklist.md` before finishing.
+- **Human engineers** — read `README.md` → `MANIFEST.md` → `core/` for onboarding, then the domains relevant to your work.
+- **Reviewers** — use `review/peer-review-checklist.md` and `review/anti-patterns.md`.
+
+## Quickstart
+
+### For Agents
+
+1. Read `core/first-principles.md` (the 8 axioms)
+2. Read `core/conflict-resolution.md` (how to resolve rule conflicts)
+3. Read `domains/<your-task-domain>/first-principles.md`
+4. Read `domains/<your-task-domain>/<topic>.md` as needed
+5. Run `review/agent-checklist.md` before completing
+
+### For Humans
+
+1. Read this README
+2. Read `MANIFEST.md` (the authoritative document index)
+3. Read `core/first-principles.md` → `core/conflict-resolution.md` → `core/reading-order.md`
+4. Pick a domain of interest and read its `first-principles.md`
+5. Skim `matrix/principles-matrix.md` to see how everything connects
+
+## The Eight Core Principles
+
+| # | Principle | One-line |
+|---|-----------|----------|
+| C1 | Correctness | The system does what it is supposed to do, and nothing else. |
+| C2 | Clarity | The intent of the code is obvious to its reader. |
+| C3 | Simplicity | The solution is as simple as possible, and no simpler. |
+| C4 | Locality | Decisions and their consequences live near each other. |
+| C5 | Reversibility | Every decision can be undone, and the cost of undoing is known. |
+| C6 | Composability | Parts combine into wholes, and the parts are reusable. |
+| C7 | Observability | The system's behavior is visible to those who must understand it. |
+| C8 | Economy | The system uses no more resources than the task requires. |
+
+Precedence: C1 > C2 > C3 > C4 > C5 > C6 > C7 > C8. Correctness is never sacrificed.
+
+## The Domains
+
+| Domain | First Principles | Derived Docs |
+|--------|------------------|--------------|
+| UI/UX | ✓ | components, accessibility, tokens, copywriting |
+| API | ✓ | rest, graphql, versioning, error-responses, pagination |
+| Security | ✓ | authentication, authorization, input-validation, secrets, supply-chain |
+| Data | ✓ | schema-design, migrations, indexing |
+| Testing | ✓ | pyramid, fixtures |
+| Performance | ✓ | frontend, backend |
+| Observability | ✓ | logging, metrics, tracing |
+| Errors | ✓ | patterns |
+| Documentation | ✓ | doc-templates |
+| Concurrency | ✓ | patterns |
+| DevOps | ✓ | ci-cd, environments |
+
+## Repository Structure
+
+```
+atelier/
+├── core/           # The 8 universal principles (read first)
+├── domains/        # 11 domains, each with first-principles + derived docs
+├── languages/      # Language-specific application of domain rules
+├── review/         # Checklists and anti-patterns
+├── matrix/         # Cross-reference: domain ↔ core
+├── examples/       # Worked examples (good + bad)
+├── MANIFEST.md     # Authoritative document index
+└── README.md       # This file
+```
+
+## License
+
+MIT. See `LICENSE`.
+
+## Contributing
+
+See `CONTRIBUTING.md`.
+
+## Version
+
+This is v0.1. See `CHANGELOG.md` for version history.

core/conflict-resolution.md

@@ -0,0 +1,105 @@
+# Core — Conflict Resolution
+
+**Status:** Foundational
+**Audience:** All agents and humans. Read after `first-principles.md`.
+
+## 1. Why Conflict Resolution Exists
+
+Atelier has eight core principles and eleven domains, each with ten principles. Rules will conflict. When they do, there must be a deterministic procedure to resolve the conflict — not a debate. This document is that procedure.
+
+## 2. The Hierarchy (Strict)
+
+```
+core/first-principles.md          ← highest authority
+  └── domains/<x>/first-principles.md
+        └── domains/<x>/<topic>.md
+              └── languages/<lang>.md
+                    └── examples/<x>.md   ← lowest authority
+```
+
+**Rules:**
+
+1. A higher document overrides a lower document when they conflict.
+2. `core/first-principles.md` is never overridden.
+3. Within a level, the more specific document wins for its specific scope.
+4. If two documents at the same level conflict with equal specificity, the core principle they each derive from decides — the higher-precedence core principle wins.
+
+## 3. Core Principle Precedence (Total Order)
+
+```
+C1 Correctness > C2 Clarity > C3 Simplicity > C4 Locality >
+C5 Reversibility > C6 Composability > C7 Observability > C8 Economy
+```
+
+- **C1 is never sacrificed.** No other principle, domain rule, or convenience overrides correctness.
+- **C2 is sacrificed only for C1.** Clarity gives way only when making code correct makes it unavoidably unclear (rare; usually clarity and correctness align).
+- **C3 is sacrificed only for C1 or C2.** Simplicity yields to correctness and clarity.
+- **C4–C8 are tradeable** among themselves, but always below C1–C3. Their relative order is: Locality > Reversibility > Composability > Observability > Economy.
+- The precedence is **total**: a violation of a higher principle is never justified by appeal to a lower one.
+
+## 4. Conflict Resolution Procedure
+
+When two rules conflict:
+
+### Step 1 — Identify the level of each rule
+- Is it core, domain-first-principles, domain-topic, language, or example?
+
+### Step 2 — Apply the hierarchy
+- The higher-level rule wins. Done.
+- If same level, proceed to Step 3.
+
+### Step 3 — Identify the core derivation
+- Look up each rule in `matrix/principles-matrix.md`.
+- Each rule derives from one or more core principles (e.g., Security P2 derives from C3 and C8).
+
+### Step 4 — Apply core precedence
+- Compare the highest-precedence core principle each rule derives from.
+- The rule deriving from the higher-precedence core principle wins.
+- Example: a rule deriving from C1 (Correctness) beats a rule deriving from C8 (Economy), always.
+
+### Step 5 — If still tied, the more specific scope wins
+- A rule scoped to "API endpoints" wins over a rule scoped to "all code" for API endpoint conflicts.
+- A rule scoped to "TypeScript" wins over a rule scoped to "all languages" for TypeScript conflicts.
+
+### Step 6 — If still tied, the conflict is a defect
+- File an issue. One of the rules is wrong. Do not silently pick one.
+- The matrix should not produce ties. If it does, the matrix is incomplete.
+
+## 5. Worked Examples
+
+### Example A: Security P9 (Secret Hygiene) vs DevOps P9 (Documentation in Pipeline)
+- Both are domain-level. Same level → Step 3.
+- Security P9 derives from C6, C7 (per matrix).
+- DevOps P9 derives from C2 (per matrix).
+- C2 > C6 and C7? **No** — C2 is precedence 2, C6 is 6, C7 is 7. C2 is higher.
+- But wait: Security P9 is **non-tradeable** per the security domain's own conflict resolution. Security's manifesto says 8 of 10 principles are never sacrificed.
+- **Resolution:** Security domain's non-tradeable declaration is a domain-level rule that itself derives from C1 (Correctness — security failures are correctness failures). So Security P9 effectively derives from C1. C1 > C2. **Security P9 wins.** Do not log secrets in the pipeline.
+- **Lesson:** A domain's "never sacrificed" declaration promotes those rules to C1-equivalent.
+
+### Example B: Performance P8 (Budget Discipline) vs Clarity (C2)
+- Performance P8 is domain-level, derives from C8 (Economy).
+- Clarity is core-level (C2).
+- Core > domain. **C2 Clarity wins.** Clear code that is slightly over budget beats opaque code that is under budget.
+- **Exception:** if the budget is a correctness requirement (e.g., real-time system), the budget derives from C1, and C1 > C2. Then the budget wins.
+
+### Example C: API P5 (Versioning) vs API P10 (Stability)
+- Both are in the same domain (api), same level.
+- API P5 derives from C5 (Reversibility). API P10 derives from C5 (Reversibility). Same core derivation — tied.
+- API's own conflict resolution (in `domains/api/first-principles.md` §3): "Versioning — never sacrificed." So P5 wins.
+- **Resolution:** Versioning wins. You version the change rather than break stability, because versioning is the mechanism that enables stability. They are not actually in conflict — versioning is how you preserve stability.
+
+## 6. Non-Tradeable Declarations
+
+Some domains declare certain principles non-tradeable (e.g., Security: 8 of 10). These declarations are binding:
+
+- A non-tradeable domain rule is treated as deriving from C1 (Correctness), regardless of its matrix entry.
+- This is because the domain has asserted that violating the rule is a correctness failure in that domain's scope.
+- Non-tradeable rules can still conflict with each other (e.g., two security rules). The domain's own precedence (in its §3) resolves those.
+
+## 7. The Matrix is the Arbiter
+
+`matrix/principles-matrix.md` is the single source of truth for derivations. If a rule is not in the matrix, it is not part of the framework. If the matrix and a domain document disagree, **the matrix wins** — the domain document must be corrected to match the matrix, or the matrix must be updated with a new derivation (a docs change, not a silent edit).
+
+## 8. Conflicts with This Document
+
+If `core/conflict-resolution.md` conflicts with `core/first-principles.md`, `first-principles.md` wins. This document is the procedure; the principles are the authority.

core/first-principles.md

@@ -0,0 +1,114 @@
+# Core — First Principles
+
+**Version:** 1.0.0
+**Status:** Foundational
+**Audience:** All agents and humans. Read this first.
+
+## 1. Manifesto
+
+There are eight principles from which all other principles derive. Every domain rule, every language rule, every review checklist traces back to one or more of these. When two rules conflict, the higher-precedence core principle wins. When a rule has no derivation here, it is orphaned and must be removed or re-derived.
+
+These principles are universal. They apply to every language, every domain, every system. They are not opinions; they are the axioms of quality software.
+
+## 2. The Principles
+
+### C1. Correctness
+The system does what it is supposed to do, and nothing else.
+
+- Correctness is the highest principle. No other principle overrides it.
+- A correct system handles the specified cases, the edge cases, and the failure cases — all defined by the domain.
+- Incorrect code that is fast, clear, or simple is still wrong.
+- Security is a subset of correctness: code that is exploitable does not do what it was supposed to do.
+- Correctness includes temporal correctness: a late answer is a wrong answer when the deadline mattered.
+
+### C2. Clarity
+The intent of the code is obvious to its reader.
+
+- Code is read more than it is written. Optimize for the reader.
+- Names reveal intent. Comments explain why, not what.
+- A stranger should understand the code without reading the documentation. The documentation should make the code unnecessary to read.
+- Clarity serves correctness: unclear code is where bugs hide.
+
+### C3. Simplicity
+The solution is as simple as possible, and no simpler.
+
+- Complexity is the enemy of correctness. Every line of code is a liability.
+- Simplicity is not laziness. It is the result of removing everything unnecessary.
+- A simple solution handles the requirement completely. A simpler-than-necessary solution does not.
+- Simplicity serves economy: less code, less to test, less to maintain.
+
+### C4. Locality
+Decisions and their consequences live near each other.
+
+- State, logic, and side effects that depend on each other live near each other.
+- Locality serves clarity: to understand a piece of code, you should not need to read the whole system.
+- Locality serves correctness: coupling that is far apart is coupling you cannot see.
+- A change that requires touching many distant files is a locality violation.
+
+### C5. Reversibility
+Every decision can be undone, and the cost of undoing is known.
+
+- Reversibility serves safety: an irreversible decision is a bet you cannot hedge.
+- Migrations, deployments, schema changes, and API changes are reversible by default.
+- A decision that cannot be reversed is made with the maximum of evidence and the minimum of haste.
+- Versioning, feature flags, and rollback paths are the mechanisms of reversibility.
+
+### C6. Composability
+Parts combine into wholes, and the parts are reusable in new wholes.
+
+- Composability serves scale: complex systems are built from simple, composable parts.
+- A part that does one thing well composes. A part that does many things configures.
+- The boundary of a part is its contract. Contracts are explicit and stable.
+- Composability serves clarity: composable parts are understandable in isolation.
+
+### C7. Observability
+The system's behavior is visible to the people who must understand it.
+
+- Observability serves correctness: you cannot fix what you cannot see.
+- Logs, metrics, and traces are first-class. They are designed in, not bolted on.
+- Observability serves clarity: the system explains itself in production.
+- An observable system answers "what happened, why, and what next?" without reading the source.
+
+### C8. Economy
+The system uses no more resources than the task requires.
+
+- Resources include time, memory, attention, money, and complexity.
+- Economy serves simplicity: the cheapest solution is often the simplest.
+- Economy is the most tradeable principle: it is sacrificed for correctness, clarity, and reversibility.
+- But unbounded economy is a bug: unbounded growth in any resource is a defect.
+
+## 3. Precedence
+
+When principles conflict, the lower-numbered principle wins:
+
+```
+C1 Correctness > C2 Clarity > C3 Simplicity > C4 Locality >
+C5 Reversibility > C6 Composability > C7 Observability > C8 Economy
+```
+
+- C1 (Correctness) is never sacrificed.
+- C2 (Clarity) is sacrificed only for C1 (Correctness).
+- C3 (Simplicity) is sacrificed only for C1 or C2.
+- C4–C8 are tradeable among themselves, but always below C1–C3.
+- The precedence is total: a violation of C1 is never justified by an appeal to C8.
+
+See `core/conflict-resolution.md` for the formal conflict resolution procedure.
+
+## 4. What Violates These Principles
+
+| Violation | Principle Breached |
+|-----------|-------------------|
+| Code that "mostly works" | C1 Correctness |
+| A function named `doStuff` | C2 Clarity |
+| A 500-line function that could be 50 | C3 Simplicity |
+| Config in a distant repo, code reads it silently | C4 Locality |
+| A migration with no rollback | C5 Reversibility |
+| A component that reads global state implicitly | C6 Composability |
+| A service with no logs | C7 Observability |
+| Loading all records into memory | C8 Economy |
+
+## 5. Relationship to Domains
+
+Every domain in Atelier derives its own P1–P10 principles from these eight. The mapping is recorded in `matrix/principles-matrix.md`. A domain rule that cannot be traced to a core principle is orphaned and must be removed.
+
+The eight principles are the floor. The domain principles are the ceiling for their scope. Within a domain, the domain's precedence applies; across domains, the core precedence applies.

core/reading-order.md

@@ -0,0 +1,103 @@
+# Core — Reading Order
+
+**Status:** Foundational
+**Audience:** New readers (agents and humans). Read after `first-principles.md` and `conflict-resolution.md`.
+
+## 1. The Canonical Order
+
+This is the order in which the framework is designed to be consumed. Following it ensures you build the mental model before the details.
+
+### For All Readers
+
+1. **`core/first-principles.md`** — The eight axioms. Everything derives from these. Read first, always.
+2. **`core/conflict-resolution.md`** — How to resolve disagreements between rules. Read second, always.
+3. **`core/reading-order.md`** — This document. You are here.
+
+### For a Specific Task
+
+4. **`domains/<relevant>/first-principles.md`** — The domain's ten principles. Read the domain(s) relevant to your task.
+5. **`domains/<relevant>/<topic>.md`** — The domain's derived topic docs. Read only what your task needs.
+
+### For Reference
+
+6. **`matrix/principles-matrix.md`** — The full mapping of every domain principle to its core derivation. Consult when a rule's authority is unclear or a conflict arises.
+7. **`MANIFEST.md`** — The authoritative index of all framework documents. If a document is not here, it is not part of the framework.
+
+### For Evaluation
+
+8. **`review/agent-checklist.md`** — The pre-completion checklist. Agents run this before finishing a task.
+9. **`review/peer-review-checklist.md`** — The human review checklist.
+10. **`review/anti-patterns.md`** — Catalog of known violations.
+
+### For Language-Specific Application
+
+11. **`languages/<lang>.md`** — How the domain principles apply in a specific language. Read only for the language you are working in.
+
+### For Illustration
+
+12. **`examples/good/*`** — Worked examples of the framework applied correctly.
+13. **`examples/bad/*`** — Worked examples of violations, with the breached principles cited.
+
+## 2. Reading Paths
+
+### Path A: New Agent (Pre-Task)
+
+```
+core/first-principles.md
+  → core/conflict-resolution.md
+    → core/reading-order.md
+      → domains/<task-domain>/first-principles.md
+        → domains/<task-domain>/<topic>.md
+          → review/agent-checklist.md (run before completing)
+```
+
+Estimated time: 15–25 minutes depending on domain depth.
+
+### Path B: New Human (Onboarding)
+
+```
+README.md
+  → MANIFEST.md
+    → core/first-principles.md
+      → core/conflict-resolution.md
+        → core/reading-order.md
+          → one domain of personal interest (e.g., domains/api/first-principles.md)
+            → matrix/principles-matrix.md (skim)
+```
+
+Estimated time: 30–45 minutes for a full pass.
+
+### Path C: Conflict Resolution
+
+```
+core/conflict-resolution.md (procedure)
+  → matrix/principles-matrix.md (look up both rules' derivations)
+    → core/first-principles.md (apply precedence)
+```
+
+Estimated time: 5 minutes per conflict.
+
+### Path D: Review
+
+```
+review/agent-checklist.md (or peer-review-checklist.md)
+  → for each failed checklist item, follow Path C
+    → examples/bad/* for the relevant violation pattern
+```
+
+## 3. What Not to Read First
+
+- **Do not** start with `examples/`. Examples illustrate principles you have not yet read.
+- **Do not** start with `languages/`. Language rules derive from domain rules you have not yet read.
+- **Do not** start with `matrix/`. The matrix is a reference, not a tutorial.
+- **Do not** skip `core/`. Everything depends on it.
+
+## 4. Skipping is Allowed After Core
+
+After reading `core/` (the three foundational documents), you may skip freely. The domains are independent of each other. You do not need to read `domains/security/` to use `domains/api/`. You only need the domain relevant to your task.
+
+The one exception: `matrix/principles-matrix.md` references all domains. You do not need to read all domains to use the matrix, but the matrix is most useful when you have read at least one domain.
+
+## 5. Versioning
+
+The framework versions as a whole (semantic versioning). A change to `core/first-principles.md` is a major version. A new domain is a minor version. A new topic doc is a patch. See `CHANGELOG.md` for the version history.