# Spec: Repository Structure

The directory layout contract for ASW. Defines what lives where and the boundary rules.

## Directory Map

```
asw/
  src/                  Framework CSS source
    layers/             Numbered CSS layer files (00-reset through 12-landing)
    main.css            Entry point — @import chain for all layers
    lab/                Experiments and test pages (not published)
  dist/                 Built output (committed to repo)
    asw.css             Single concatenated file
    asw.min.css         Minified
  vendor/               Explicit external dependencies
    open-props/         Open Props CSS (with VERSION file)
    README.md           What's vendored, why, how to update
  packs/                Engine integration bundles
    hugo/               Hugo theme/partial integration
    apache/             Apache autoindex + error pages
    caddy/              Caddy browse + error pages
    flask/              Flask error handlers
    nginx/              Nginx autoindex + error pages
    pandoc/             Pandoc HTML5 template + Lua filter
    python/             Python HTTP server with ASW styling
  docs/                 Framework documentation (markdown only)
  examples/             Static HTML showcases (no build step needed)
  site/                 The ASW website (currently uses Hugo pack)
    content/            Site-specific content (articles, essays, notes)
    layouts/            Hugo templates
    hugo.toml           Hugo config (mounts docs/ as content/docs/)
    static/             Site static assets
  openspec/             Specs and changes
```

## Boundary Rules

### src/ — framework only
- Contains only CSS source files and lab experiments
- No Hugo-specific files, no content, no templates
- `main.css` imports from `layers/` using relative paths
- `lab/` contains HTML files that reference layers directly — never published

### dist/ — build artifacts, committed
- Built by PostCSS from `src/main.css`
- Committed to repo so consumers can grab without a build step
- Regenerated on deploy, not manually edited

### vendor/ — visible dependencies
- Open Props source files copied from npm, with version tracking
- `VERSION` file records package version and date of last update
- Updated manually when bumping Open Props

### packs/ — engine-agnostic integrations
- Each subdirectory is a self-contained integration for one engine
- A pack may reference `dist/asw.css` or `src/layers/` depending on its needs
- Packs ship their own README

### docs/ — markdown only
- No HTML, no engine-specific markup
- The site consumes these as content source (Hugo module mount)
- GitHub/Forgejo renders these directly — no build step to read docs

### examples/ — static HTML
- Each file is a standalone demo that loads ASW
- Can be opened in a browser by cloning the repo — no build step
- The site may link to these but they exist independently

### site/ — website concerns
- All Hugo-specific files live here
- `content/docs/` is mounted from `../docs/`, not duplicated
- Site-specific content (articles, essays, notes) lives in `content/`
- Changes to the site do not affect the framework; changes to the framework may affect the site

## Scenarios

### Given a new CSS layer
- **When** an agent creates it
- **Then** it goes in `src/layers/` with the next number
- **And** `src/main.css` gets an @import line

### Given a new framework doc
- **When** an agent writes documentation
- **Then** it goes in `docs/` as a .md file
- **And** the site picks it up automatically via Hugo mount

### Given a new engine integration
- **When** someone adds support for a new engine (e.g., Eleventy)
- **Then** it goes in `packs/<engine>/` with its own README

### Given a lab experiment
- **When** an agent wants to test a CSS pattern
- **Then** it creates a file in `src/lab/`
- **And** it references layers via relative paths
- **And** it is never published to the site