docs(P06): complete languages-meta phase

CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to the Atelier framework are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-08-05
+
+### Added
+- Eight core principles (C1–C8) in `core/first-principles.md` with definitions, precedence, and violation tables.
+- Formal conflict resolution procedure in `core/conflict-resolution.md` (hierarchy, precedence, worked examples, non-tradeable declarations).
+- Canonical reading order in `core/reading-order.md` with paths for agents, humans, conflict resolution, and review.
+- README with quickstart for AI agents and humans.
+- MIT license.
+- Eleven domain first-principles (P1–P10 each): UI/UX, API, Security, Data, Testing, Performance, Observability, Errors, Documentation, Concurrency, DevOps.
+- Twenty-seven domain derived/topic docs (REST, GraphQL, versioning, error-responses, pagination, authentication, authorization, input-validation, secrets, supply-chain, schema-design, migrations, indexing, pyramid, fixtures, frontend, backend, logging, metrics, tracing, tokens, copywriting, patterns, doc-templates, patterns, ci-cd, environments).
+- `matrix/principles-matrix.md` — full mapping of all 110 domain principles to core derivations.
+- `matrix/domain-coverage.md` — inverse mapping of core principles to domains.
+- `review/agent-checklist.md` — pre-completion gate for AI agents.
+- `review/peer-review-checklist.md` — human review checklist.
+- `review/anti-patterns.md` — catalog of violations with principle citations.
+- Four good worked examples: `examples/good/api-endpoint.md`, `react-component.md`, `db-schema.md`, `error-handler.md`.
+- Three bad worked examples: `examples/bad/god-object.md`, `silent-error.md`, `leaky-abstraction.md`.
+- Four language application docs: `languages/typescript.md`, `python.md`, `go.md`, `rust.md`.
+- `MANIFEST.md` — authoritative document index.
+- `CONTRIBUTING.md` — contribution guide.
+
+### Framework Properties
+- 8 core principles, 11 domains, 110 domain principles, all traced via the matrix.
+- NFR milestone type (documentation only, no runtime code).
+- Tags: v0.0.0 (pre-execution) through v0.0.7 (final review + ship).
+- The v0.0.7 patch release IS the v0.1.0 milestone deliverable.
+
+### Phases
+- Phase 0 (v0.0.0): pre-execution — specify, clarify, research, plan, ship.
+- Phase 1 (v0.0.1): core foundation — first-principles, conflict-resolution, reading-order, README, LICENSE.
+- Phase 2 (v0.0.2): domain first-principles — uiux first-principles + audit.
+- Phase 3 (v0.0.3): domain derived docs — 27 topic files.
+- Phase 4 (v0.0.4): matrix + review — domain-coverage, agent-checklist, peer-review-checklist, anti-patterns.
+- Phase 5 (v0.0.5): examples — 4 good + 3 bad.
+- Phase 6 (v0.0.6): languages + meta — typescript, python, go, rust, CHANGELOG, CONTRIBUTING.
+- Phase 7 (v0.0.7): final review + ship — milestone release.

CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing to Atelier
+
+Thank you for considering a contribution to Atelier. This framework lives by its principles; contributions are expected to follow them.
+
+## What We Accept
+
+- **New domain first-principles** — if a domain is missing (e.g., `domains/ai-ml/`), propose it with 10 principles (P1–P10), each traced to a core principle (C1–C8) in `matrix/principles-matrix.md`.
+- **New domain derived docs** — topic docs under an existing domain (e.g., `domains/api/webhooks.md`), deriving from the domain's first-principles.
+- **New language application docs** — `languages/<lang>.md` showing how domain principles apply in a specific language.
+- **New examples** — `examples/good/*` (with principle citations) or `examples/bad/*` (with violation citations).
+- **Corrections** — to existing principles, derivations, or examples. A correction to a core principle is a major version change; treat with care.
+- **Improvements to the matrix** — if a derivation is missing or wrong, propose the fix with the rationale.
+
+## What We Do Not Accept
+
+- **Style rules** — Atelier is principles, not style. Use a linter for style.
+- **Tooling** — linters, analyzers, or enforcement code. Atelier is markdown.
+- **Unlisted docs** — every document must be in `MANIFEST.md`. An unlisted doc is not part of the framework.
+- **Principles without derivation** — a domain principle that does not trace to a core principle is orphaned and will be rejected.
+
+## How to Contribute
+
+### 1. Read the relevant docs first
+- `core/first-principles.md` — the eight axioms.
+- `core/conflict-resolution.md` — how conflicts are resolved.
+- The domain(s) you are contributing to.
+- `matrix/principles-matrix.md` — to see existing derivations.
+
+### 2. Follow the document structure
+See `domains/documentation/doc-templates.md` for the canonical structure. Every first-principles doc has:
+- Manifesto
+- The Principles (P1–P10, named, defined, with "what violates it")
+- Conflict Resolution
+- What Violates These Principles (table)
+- Relationship to Core
+
+### 3. Update the matrix
+If you add or change a principle, update `matrix/principles-matrix.md` with the derivation. A PR with a new principle but no matrix row is incomplete.
+
+### 4. Update the manifest
+If you add a new document, add it to `MANIFEST.md` in the correct section. An unlisted document is not part of the framework.
+
+### 5. Add examples
+If you add a principle, add at least one good example and one bad example in `examples/`. Examples are mandatory (Documentation P3).
+
+### 6. Write a clear PR description
+- What principle or document you are adding/changing.
+- Why (the rationale, not just the what — Documentation P8 Why Over What).
+- Which core principle(s) it derives from.
+- What conflicts it might introduce (if any).
+
+## Review Criteria
+
+Reviewers will check (see `review/peer-review-checklist.md`):
+- Does the new principle trace to a core principle?
+- Is the matrix updated?
+- Is the manifest updated?
+- Are there examples?
+- Does the structure follow the template?
+- Does it conflict with existing principles? If so, is the conflict resolvable per `core/conflict-resolution.md`?
+
+## Versioning
+
+- A new domain or language doc is a minor version (e.g., v0.1 → v0.2).
+- A new topic doc or example is a patch version (e.g., v0.1.0 → v0.1.1).
+- A change to `core/first-principles.md` (adding, removing, or reordering a core principle) is a major version (e.g., v0.x → v1.0).
+- See `CHANGELOG.md` for the version history.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the MIT license (see `LICENSE`).

languages/go.md

@@ -0,0 +1,82 @@
+# Go — Language Application
+
+> How Atelier's domain principles apply in Go specifically. Derives from `domains/` docs.
+
+## Type System (C1 Correctness, Data P7 Type Fidelity)
+
+- **Named types for domain concepts:** `type UserId string`, not bare `string`.
+- **No `interface{}`/`any` without justification:** Go 1.18+ generics reduce the need.
+- **`any` requires a type assertion or switch:** never use the value without narrowing.
+
+```go
+type UserId string
+type OrderId string
+// UserId and OrderId are distinct; cannot be mixed
+func GetUser(id UserId) (*User, error) { ... }
+```
+
+## Error Handling (Errors P1 Errors are Data)
+
+- **Errors are values:** `error` is an interface, not an exception. Handle explicitly.
+- **Sentinel errors with `errors.Is`:**
+```go
+var ErrNotFound = errors.New("not found")
+if errors.Is(err, ErrNotFound) { ... }
+```
+- **Wrap with context:** `fmt.Errorf("get user %d: %w", id, err)`.
+- **Never `_ = err`:** swallowed error (Errors P2). Handle or return.
+- **Custom error types with `errors.As`:**
+```go
+type ValidationError struct {
+    Field string
+    Msg  string
+}
+func (e *ValidationError) Error() string { return e.Field + ": " + e.Msg }
+```
+
+## Concurrency (Concurrency — Go's strength)
+
+- **Goroutines + channels** for message passing (P5 Lock Minimization).
+- **`context.Context` for cancellation and timeout:** every function that does I/O takes a `ctx`.
+- **`sync.Mutex` scoped minimally:** not held across I/O (P3 Lock Scope).
+- **Bounded channels:** `make(chan T, N)`, not unbounded (P9 Bounded Queues).
+
+```go
+func fetchWithTimeout(ctx context.Context, url string) (*Response, error) {
+    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+    defer cancel()
+    return doFetch(ctx, url)
+}
+```
+
+## Immutability (Concurrency P1)
+
+- **Pass by value for small structs; pass by pointer for large or mutable.**
+- **No mutation of method receivers:** use a value receiver, not a pointer receiver, for read-only methods.
+- **Copy-on-write for shared state:** return a new struct, not a mutated one.
+
+## Nullability (C1)
+
+- **Pointers can be nil; values cannot.** Be explicit: `*User` (nullable) vs `User` (not).
+- **`nil` check before deref:** a nil deref is a panic.
+- **Return `(T, error)`, not `(*T, nil)`:** avoid the "nil pointer" trap.
+
+## Testing (Testing)
+
+- **`testing` package + `testify/assert`** or stdlib only.
+- **Table-driven tests:** `[]struct{ name string; input X; want Y }`.
+- **`t.Parallel()`** for independent tests (P2 Independence).
+- **`httptest` for HTTP handlers; `sqlite` or testcontainers for DB.**
+
+## Observability (Observability P1)
+
+- **`slog` (stdlib, Go 1.21+) or `zap`/`zerolog`:** structured logs.
+- **`context.Context` carries `trace_id`:** propagated via middleware.
+- **No `fmt.Println`:** use the logger.
+
+## Tooling (DevOps P2)
+
+- **`go vet` + `golangci-lint`:** lint.
+- **`gofmt`/`goimports`:** format (automated, not debated).
+- **`go test -race` in CI:** race detector (Concurrency P6 No Silent Races).
+- **`go mod tidy` + committed `go.sum`:** reproducible builds.

languages/python.md

@@ -0,0 +1,77 @@
+# Python — Language Application
+
+> How Atelier's domain principles apply in Python specifically. Derives from `domains/` docs.
+
+## Type System (C1 Correctness, Data P7 Type Fidelity)
+
+- **Type hints on every function:** `def get_user(id: UUID) -> User | None:`.
+- **`mypy --strict` or `pyright` in CI:** type check is not optional.
+- **No `Any` without justification:** `Any` disables the type checker. Use `object` + narrowing.
+- **Pydantic for runtime validation:** schemas validate and type at the boundary.
+
+```python
+from pydantic import BaseModel
+from uuid import UUID
+
+class UserCreate(BaseModel):
+    email: str
+    name: str
+    # additionalProperties: false by default (extra='forbid')
+```
+
+## Error Handling (Errors P1 Errors are Data)
+
+- **Exceptions for exceptional cases,** not control flow. `raise` not `return None` for errors.
+- **Custom exception hierarchy:**
+```python
+class AppError(Exception): pass
+class ValidationError(AppError): pass
+class NotFoundError(AppError): pass
+```
+- **Never bare `except:`:** `except Exception as e:` (catch specific, not everything).
+- **Never `except: pass`:** log and re-raise or handle, never swallow (Errors P2).
+
+## Async (Concurrency P7, P8)
+
+- **`asyncio` for I/O-bound:** `async def`, `await`. Not threads for I/O.
+- **`anyio` for portability** if you may switch runtimes (trio compatibility).
+- **Timeout on every `await`:** `asyncio.wait_for(coro, timeout=5)`, not bare `await`.
+- **Cancellation propagated:** `asyncio.CancelledError` is not caught; it propagates.
+
+## Immutability (Concurrency P1)
+
+- **`frozen=True` dataclasses** for value objects:
+```python
+from dataclasses import dataclass
+@dataclass(frozen=True)
+class UserId:
+    value: str
+```
+- **Tuples over lists** for fixed-length, immutable sequences.
+- **No in-place mutation of shared state:** return new objects.
+
+## Nullability (C1)
+
+- **`Optional[T]` is `T | None`:** explicit, must be checked.
+- **`None` is not "not found":** raise `NotFoundError` or return `Result`, not `None`.
+- **`assert` is for invariants,** not for runtime checks (stripped with `-O`).
+
+## Testing (Testing)
+
+- **pytest** with fixtures (factories, not shared state).
+- **`pytest --randomly`** to catch order-dependent tests (P2 Independence).
+- **`freezegun` for time:** no `datetime.now()` in tests; inject the clock.
+- **`factory_boy` or `pytest-factoryboy`** for realistic factories.
+
+## Observability (Observability P1)
+
+- **`structlog` or `python-json-logger`:** JSON logs, not `print`.
+- **`logging` with structured formatter:** every log has `request_id`, `user_id`, `event`.
+- **No secrets in logs:** `mask_secret()` helper, or `structlog` processors.
+
+## Tooling (DevOps P2)
+
+- **`ruff` for lint + format:** replaces flake8 + black + isort.
+- **`mypy --strict` in CI:** type check.
+- **`pip-tools` or `poetry` for lockfile:** pinned dependencies.
+- **`pip install --no-deps -r requirements.txt`:** reproducible install.

languages/rust.md

@@ -0,0 +1,79 @@
+# Rust — Language Application
+
+> How Atelier's domain principles apply in Rust specifically. Derives from `domains/` docs.
+
+## Type System (C1 Correctness, Data P7 Type Fidelity)
+
+- **Newtypes for domain concepts:** `struct UserId(String);` — zero-cost, type-safe.
+- **`enum` for finite domains:** `enum Status { Pending, Paid, Shipped }` — exhaustive.
+- **No `unsafe` without justification and review:** `unsafe` opts out of the compiler's guarantees.
+
+```rust
+struct UserId(String);
+struct OrderId(String);
+// Cannot pass OrderId where UserId is expected
+fn get_user(id: UserId) -> Result<User, Error> { ... }
+```
+
+## Error Handling (Errors P1 Errors are Data)
+
+- **`Result<T, E>` for fallible operations:** errors are values, not exceptions.
+- **`thiserror` for error enums, `anyhow` for applications:**
+```rust
+#[derive(thiserror::Error)]
+enum AppError {
+    #[error("not found: {0}")]
+    NotFound(String),
+    #[error("validation: {0}")]
+    Validation(String),
+    #[error(transparent)]
+    Io(#[from] std::io::Error),
+}
+```
+- **`?` for propagation, not `unwrap()`:** `unwrap()` panics in production.
+- **No `panic::catch_unwind` for control flow:** panics are for bugs, not errors.
+
+## Concurrency (Concurrency — Rust's ownership model)
+
+- **`Send` and `Sync` traits enforced by the compiler:** data races are compile errors.
+- **`Arc<T>` for shared, `Mutex<T>`/`RwLock<T>` for mutation:** the lock is explicit.
+- **`tokio` for async:** `async fn`, `.await`. Bounded channels (`tokio::sync::mpsc::channel(N)`).
+- **`Drop` for cleanup:** no leaked resources (no `defer` needed; RAII).
+
+```rust
+async fn fetch_with_timeout(url: &str) -> Result<Response, Error> {
+    tokio::time::timeout(Duration::from_secs(5), fetch(url)).await??;
+}
+```
+
+## Immutability (Concurrency P1 Immutability by Default)
+
+- **Variables are immutable by default:** `let x = 5;` not `let mut x = 5;`.
+- **`&T` (shared ref) over `&mut T` (exclusive ref):** the compiler enforces aliasing rules.
+- **Interior mutability (`Cell`/`RefCell`) only when needed:** not as a default.
+
+## Nullability (C1)
+
+- **`Option<T>`, not nullable pointers:** `Some(x)` / `None`. The compiler enforces handling.
+- **No `null`:** Rust has no null. `Option::None` is the explicit absence.
+- **`?` on `Option` for propagation:** `fn get_name(user: User) -> Option<String> { user.profile?.name }`.
+
+## Testing (Testing)
+
+- **`#[test]` + `#[cfg(test)] mod tests`:** tests co-located.
+- **`proptest` or `quickcheck` for property-based tests:** edge case coverage (P9).
+- **`tokio::test` for async tests.**
+- **No `SystemTime::now()` in tests:** inject an `Instant` or a mock clock.
+
+## Observability (Observability P1)
+
+- **`tracing` crate:** structured logs + spans + traces. Not `println!`.
+- **`tracing::instrument` on functions:** automatic span context.
+- **`tracing-subscriber` with JSON format:** structured output for production.
+
+## Tooling (DevOps P2)
+
+- **`cargo clippy`:** lint. `cargo clippy -- -D warnings` in CI.
+- **`cargo fmt`:** format.
+- **`cargo test`:** tests. `cargo test --release` for perf-sensitive.
+- **Committed `Cargo.lock`:** reproducible builds (even for libraries, for CI).

languages/typescript.md

@@ -0,0 +1,76 @@
+# TypeScript — Language Application
+
+> How Atelier's domain principles apply in TypeScript specifically. Derives from `domains/` docs; this file is the language-specific lens.
+
+## Type System (C1 Correctness, Data P7 Type Fidelity)
+
+- **Strict mode on:** `strict: true` in `tsconfig.json`. No `any` without justification.
+- **No `any`, no `unknown` without narrowing:** `any` disables the type checker. `unknown` requires narrowing before use.
+- **Discriminated unions over enums:** `type Status = { type: 'pending' } | { type: 'paid'; amount: number }` — exhaustive, type-safe.
+- **Branded types for domain IDs:** `type UserId = string & { __brand: 'UserId' }` — prevents passing a `PostId` where a `UserId` is expected.
+
+```typescript
+type UserId = string & { readonly __brand: 'UserId' };
+function getUser(id: UserId): User { ... }
+// getUser("abc")          // type error
+// getUser("abc" as UserId) // ok
+```
+
+## Error Handling (Errors P1 Errors are Data)
+
+- **Result type over exceptions for expected failures:**
+```typescript
+type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
+```
+- **Exceptions for programmer errors:** null deref, invariant violation. Not for "user not found."
+- **Never `any` in catch:** `catch (e: unknown)` then narrow with `instanceof` or a type guard.
+
+## Async (Concurrency P7 Cancellation Support, P8 Timeout Discipline)
+
+- **`Promise` with `AbortSignal`:** every async function accepts an optional `AbortSignal` for cancellation.
+- **`Promise.race` with a timeout:** never `await` without a timeout for external calls.
+- **No `await` in a hot loop without batching:** use `Promise.all` for parallelism.
+
+```typescript
+async function fetchWithTimeout(url: string, signal?: AbortSignal): Promise<Response> {
+  const timeout = new AbortController();
+  signal?.addEventListener('abort', () => timeout.abort());
+  const timer = setTimeout(() => timeout.abort(), 5000);
+  try {
+    return await fetch(url, { signal: timeout.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+```
+
+## Immutability (Concurrency P1 Immutability by Default)
+
+- **`readonly` on arrays and objects:** `readonly string[]`, `readonly { id: string }`.
+- **`as const` for literals:** `const status = 'pending' as const`.
+- **Immutable update patterns:** `spread` or `Immer` for nested updates, never mutation.
+
+## Nullability (C1 Correctness)
+
+- **`strictNullChecks: true`:** `null` and `undefined` are distinct and must be handled.
+- **No `!` (non-null assertion) without justification:** it disables the null check. Use narrowing.
+- **`optional chaining` over `&&`:** `user?.profile?.name` not `user && user.profile && user.profile.name`.
+
+## Testing (Testing)
+
+- **Jest or Vitest** with `ts-jest`/`vite`. Test files co-located: `user.ts` → `user.test.ts`.
+- **Factories over fixtures:** `makeUser()` returns a fresh object per test.
+- **No `Date.now()` in tests:** inject the clock. `jest.useFakeTimers()` or pass a `now` function.
+
+## Observability (Observability P1 Structured by Default)
+
+- **Structured logger:** `pino` or `winston` in JSON mode. Not `console.log`.
+- **`request_id` via middleware:** propagated on every log in the request.
+- **No secrets in logs:** the logger redacts known secret fields (`pino` redact option).
+
+## Tooling (DevOps P2 Automation)
+
+- **ESLint with `@typescript-eslint`** — strict ruleset.
+- **Prettier** — format, not debated.
+- **`tsc --noEmit` in CI** — type check without emitting.
+- **`npm ci`** — lockfile install, not `npm install`.