diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..32b844e
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,48 @@
+# CLAUDE.md — config (personal dotfiles)
+
+Project context for Claude. Global preferences in `~/.claude/CLAUDE.md` apply on top.
+
+## What this is
+
+Personal dotfiles repo. **Archetype: dotfiles-meta** (meta/config, not an application).
+Produces vim + bash configuration deployed by `install.sh`. Private/personal audience.
+
+- Public: no
+- Database: none
+- Stack: POSIX/bash shell scripts + vimscript
+- Distribution: `git clone` + `./install.sh <target>`
+
+## Layout
+
+```
+remote-install.sh     curl|bash bootstrap: ensure git, clone/pull, run install.sh
+install.sh            one-shot installer (OS auto-detected)
+vim/vimrc             vim config (pathogen, molokai, syntastic, NERDTree)
+vim/autoload/         pathogen loader (committed)
+vim/colors/           molokai colorscheme (committed)
+bash/bashrc-{linux,osx}          OS-detected bashrc
+.claude/{tasks,memory,audits}/   Claude working state
+```
+
+## Commands
+
+| Task  | Command                                  |
+| ----- | ---------------------------------------- |
+| Lint  | `shellcheck *.sh bash/bashrc-*`          |
+| Syntax check | `bash -n install.sh remote-install.sh` |
+| Install | `./install.sh` (OS auto-detected) |
+| Remote install | `curl -fsSL <raw>/remote-install.sh \| bash` |
+
+No build, no test suite. Lint = shellcheck.
+
+## Conventions
+
+- Shell scripts: `#!/usr/bin/env bash`, `set -euo pipefail`, quote all expansions, keep shellcheck clean.
+- Installer must stay **idempotent** (re-runnable without breaking state) and use `$SCRIPT_DIR`-relative paths.
+- bashrc files: tabs for indentation (existing style). Style nits (legacy backticks) tolerated — don't churn.
+- No secrets in any tracked file. Use placeholders if config ever needs tokens.
+
+## Known issues (see .claude/audits/ONBOARD_REPORT.md)
+
+- `vim/vimrc` `GenerateClassC` uses bare `name` instead of `a:name` → `:ClassC` errors (E121). Vim domain, not yet fixed.
+- bashrc files use legacy backticks (`SC2006`) — cosmetic.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3e3f14c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,59 @@
+# config
+
+Personal dotfiles — vim + bash configuration and a one-shot installer.
+
+## What's inside
+
+| Path                 | Purpose                                                        |
+| -------------------- | -------------------------------------------------------------- |
+| `install.sh`         | Backs up existing config, then deploys vim + bashrc for a target. |
+| `vim/vimrc`          | Vim config: pathogen, molokai, syntastic (C with `-Wall -Werror -Wextra`), NERDTree, 42-style canonical class generators (`:ClassH`, `:ClassC`). |
+| `vim/autoload/`      | `pathogen.vim` plugin loader (committed).                      |
+| `vim/colors/`        | `molokai.vim` colorscheme (committed).                         |
+| `bash/bashrc-linux`  | bashrc for desktop Linux (git-aware prompt + command timer).   |
+| `bash/bashrc-osx`    | bashrc for macOS.                                              |
+
+## Install
+
+### One-liner (clone + install)
+
+```sh
+curl -fsSL https://git.bchanot.fr/bchanot/config/raw/branch/master/remote-install.sh | bash
+```
+
+`remote-install.sh` ensures `git` is present, clones the repo to `~/config` (or pulls if already there), then runs `install.sh`. Override with env vars: `REPO_URL=... CLONE_DIR=... BRANCH=... curl ... | bash`.
+
+> Piping a remote script into `bash` runs unreviewed code over the network. Read [`remote-install.sh`](remote-install.sh) first, or use the manual clone below.
+
+### Manual
+
+```sh
+git clone https://git.bchanot.fr/bchanot/config.git && cd config
+./install.sh
+```
+
+No argument — the OS is auto-detected.
+
+What it does:
+
+1. On Debian/Ubuntu, installs `vim git gcc make pkg-config unzip dkms git-lfs` via `apt-get`. Skipped automatically where `apt-get` is absent (macOS).
+2. Moves any existing `~/.vim`, `~/.vimrc`, `~/.bashrc`, `~/.Sublivim` to `~/Oldconfig`.
+3. Clones the `syntastic` and `nerdtree` vim plugins into `~/.vim/bundle/`.
+4. Copies the tracked vim files into `~/.vim` and symlinks `~/.vimrc`.
+5. Picks the bashrc by OS: macOS → `bashrc-osx` (falls back to `bashrc-linux` if missing), everything else → `bashrc-linux`. Copies it to `~/.bashrc`.
+
+The script is re-runnable: each run re-backs up to `~/Oldconfig` (overwriting the previous backup) and re-clones plugins.
+
+> macOS note: the `osx` target skips `apt-get` but still expects `vim`, `git`, and a Homebrew-installed toolchain to be present.
+
+## Requirements
+
+- `bash`, `git`
+- Debian/Ubuntu `apt-get` for the package step (optional elsewhere)
+- A `bash` login shell (zsh users: switch to bash for these prompts to apply)
+
+## Lint
+
+```sh
+shellcheck install.sh bash/bashrc-*
+```