svelte-kit-vice/docs/repository.md

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

# The Repository

One tree, one install, one gate. [`docs/README.md`](./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`](./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`](./consuming.md).

## One import map

Every `$…` / `@/` specifier resolves through ONE module,
[`uix.aliases.js`](../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`](../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`](./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`](./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.