svelte-kit-vice/docs/repository.md

title	type	audience	authority	status
The Repository	reference	human + agent	reference — the zones of this repository, who may write in each, and the invariants that hold them apart	current

The Repository

One tree, one install, one gate. docs/README.md is the map of the docs; this is the map of the repository: what each zone is, who may write in it, and the few invariants that keep the zones from bleeding into each other. The path from clone to first change is getting-started.md.

The zones

Zone	What it is	Who writes it
src/uix/	The layers — morfo (contract), soma (behavior), sema (perceptual engine), eidos (CSS) — plus the active-uix composition root and the blocks tier	the framework
src/arts/ · src/libs/ · src/svrs/ · src/packs/	Runtime artifacts, zero-dependency helpers, server-authoritative engines, the opt-in pack tier	the framework
web/routes/	The demo site Kit serves (kit.files.routes). FROZEN — see below	nobody
apps/*	npm workspaces that consume the framework as source; apps/base is the reference consumer	app authors
scripts/	The tooling: validators, generators, the pre-push hook. Type-checked and owing zero, like src/	whoever adds or fixes a guard
docs/	The doc corpus (strata E0–E5), plus docs/process/ for the ephemeral record	doc authors
static/	Fonts, sounds, images served by URL; an app copies what it needs into its own static/	the framework

Two zones are NOT source: src/docs/ holds the book manuscripts the canon comes from, and src/lib/_demo holds the frozen demo site's own widgets (the $demo alias).

web/routes/ is frozen

The demo tree is being rebuilt from scratch, so it is read-only: read it as a reference for composition, never edit it. Two consequences that bite:

• the browser-driven validators (morfo:check, perm:check, smoke, layer:check) and the demo rules of component:audit validate AGAINST that frozen tree, so they stay manual until an app tree replaces them;
• web/ is in .prettierignore, so the format policy does not reach it.

One install, one workspace

The root package.json declares workspaces: ["apps/*"]: one node_modules, one lockfile, one copy of svelte, vite and @sveltejs/kit for the framework and every app. Two copies of Svelte would be two runes runtimes, and the framework's .svelte.ts modules would not share state with an app's components. Vite derives the workspace root from that field, which is what lets an app's dev server read files under src/ with no server.fs.allow. The contract an app follows — aliases, runes, composition root, CSS and assets, the pre-hydration boot — is consuming.md.

One import map

Every $… / @/ specifier resolves through ONE module, uix.aliases.js, imported by vite.config.ts, svelte.config.js, scripts/generate-boot.ts, scripts/docs-check.ts and each app's svelte.config.js. Order is load-bearing — Vite and esbuild match a string alias as a PREFIX, so a longer specifier must precede any key that is its prefix — and src/uix/aliases.test.ts fails on a second copy, a broken order, or a target that is not on disk. The table summary lives in CLAUDE.md → Path Aliases.

The framework owes zero, the demo tree owes a shrinking ledger

npm run check:gate fails on any type error under src/ or scripts/; errors in the frozen web/ tree are measured against a per-file ledger that may only shrink. That policy, the whole gate chain and the pre-push hook are in testing-and-tooling.md § The gate — with the format policy and the inventory of generated artifacts in the same page.

What is open

The framework's open rows live in one place, by id: docs/process/LEDGER-cierre-2026-09.md. It is process — a record of what happened, never a source of truth for how the framework works — but it is the only place that knows what was deferred and why. The CONTINUE-*.md hand-offs beside it are frozen and point at it.