# Claude Environment How Claude Code is configured across Guerin's `sites/` workspace. ## Three Layers The setup has three layers, each narrowing scope: 1. **Global** (`~/.claude/`) -- Claude Code application settings, memory, MCP servers 2. **Workspace** (`sites/CLAUDE.md`, `sites/.ai/`, `sites/.claude/`) -- shared instructions and documentation for every domain 3. **Per-site** (`sites/{domain}/CLAUDE.md`, `sites/{domain}/.ai/`) -- overrides and context for a single domain ``` ~/.claude/ ← Claude Code app config settings.json ← global permissions, additional directories mcp.json ← MCP servers (Bitly, etc.) projects/ c--Users-steph-Documents-sites/ memory/MEMORY.md ← persistent cross-session notes sites/ ← workspace root CLAUDE.md ← global AI instructions .ai/ ← shared reference docs .claude/settings.json ← workspace-level permissions .credentials/ ← centralized credential store {domain}/ ← one folder per domain CLAUDE.md ← site-specific instructions .ai/ ← site-specific docs and chat history .site ← route configuration (WebDAV, etc.) ``` --- ## The `.ai/` Folder `.ai/` is a convention for storing documentation that any AI tool can read. It is not Claude-specific. The same folder is referenced by Copilot, Gemini, and ChatGPT instructions. ### Top-level `.ai/` (workspace) Lives at `sites/.ai/`. Contains 18 files of shared reference material: | File | Purpose | |------|---------| | `remote-access.md` | Route types, WebDAV operations, auth patterns | | `acl.md` | Role-based access control (Mayordomo, Comisionado, Parciante, Guest) | | `hostgo-domains.md` | HostGo domain/IP mapping, ports, add-on domains | | `acequia-token.md` | JWT structure, claims, role encoding | | `acequia-wallet.md` | Inventory of current Bearer tokens with curl examples | | `browser-hosting.md` | Browsers as CDN endpoints (IndexedDB, OPFS, WebRTC) | | `glossary.md` | Domain-specific terminology | | `style-guide.md` | Code style rules (HTML/CSS, JS, Python, Markdown) | | `conventions.md` | File and naming conventions | | `chat-conventions.md` | Chat file naming (`YYYY-MM-DD-topic-slug.md`) | | `support-urls-and-files.md` | Standard URL/file input pattern for web tools | | `context.md` | General project context | | `instructions.md` | General AI instructions | | `claude.md` | Claude-specific capabilities | | `copilot.md` | GitHub Copilot notes | | `gemini.md` | Gemini notes | | `gpt.md` | ChatGPT notes | The top-level `CLAUDE.md` references several of these directly (e.g., `remote-access.md`, `acl.md`, `hostgo-domains.md`). ### Per-site `.ai/` folders Six domain folders have their own `.ai/`: - `acequia.org/.ai/` -- canonical ACL definition, chat history - `guerin-acequia-io/.ai/` -- project context, conventions, chat history - `harvardviz.live/.ai/` -- project context - `realtime.earth/.ai/` -- architecture principles - `redfish.com/.ai/` -- (empty, placeholder) - `localhost/proxy/.ai/` -- zero-dependency CORS proxy constraints Typical contents: `context.md`, `conventions.md`, `glossary.md`, and a `chats/` subfolder with dated conversation logs. ### Why `.ai/` and not `.claude/`? `.ai/` is tool-agnostic. The same documentation folder works for Copilot, Gemini, ChatGPT, and Claude. Each tool has its own top-level config file (`CLAUDE.md`, `.github/copilot-instructions.md`, etc.), but `.ai/` provides shared reference material any of them can consume. --- ## The `.claude/` Directory ### Global (`~/.claude/`) Claude Code's application directory. Key contents: | Path | Purpose | |------|---------| | `settings.json` | Global permissions (`Bash` allowed), additional working directories | | `mcp.json` | MCP server config (Bitly) | | `projects/` | Per-project state: conversation transcripts, memory, session index | | `plans/` | 36 auto-named plan files for complex task breakdowns | | `todos/` | 2000+ todo list JSON files (one per conversation) | | `file-history/` | Edit history organized by conversation ID | | `history.jsonl` | Command history | ### Workspace (`sites/.claude/`) Project-level Claude settings: - `settings.json` -- base permissions (allow Bash) - `settings.local.json` -- local overrides (MCP tools, WebFetch domain allowlist) ### Memory (`~/.claude/projects/.../memory/MEMORY.md`) Persistent notes that survive across conversations. Currently tracks: - Local folder naming convention (hyphens, not dots) - HostGo/cPanel WebDAV quirks (WebDAV root vs. `public_html`) This file is loaded into the system prompt at the start of every conversation. --- ## `CLAUDE.md` Files `CLAUDE.md` is Claude Code's project instruction file. It is loaded automatically when Claude opens a workspace. ### Top-level (`sites/CLAUDE.md`) The global instruction set. Covers: - **Git workflow** -- checkpoint commits before changes, present tense, never commit secrets - **Writing style** -- no em dashes, no "not X, but Y" constructions - **Code style** -- 2-space indent, ES6+, prefer built-in Node modules - **Credential security** -- waldo and simtable use Bearer tokens (not netrc); all others use netrc; never expose credentials in curl commands - **Local-first** -- always write files locally first; remote sync is secondary - **Multiple domains** -- pay attention to exact domain and path; use fully qualified URLs in markdown links - **Creating new sites** -- folder, credentials, manifest refresh, `.site` file - **Video conversion** -- ffmpeg workflow with mandatory `-movflags +faststart` ### Per-site CLAUDE.md (20 files) Each inherits from the top-level and adds site-specific rules. Example from `guerin.acequia.io/CLAUDE.md`: ``` Domain: guerin.acequia.io Primary: acequia.io (add-on domain) IP: 216.37.42.226 - Every HTML file includes a visible version number - Use a fixed-position element with class "version" - Increment version on every change ``` ### Inheritance ``` sites/CLAUDE.md (always loaded) ↓ sites/{domain}/CLAUDE.md (loaded when working in that folder) ↓ deeper CLAUDE.md files (e.g., realtime-earth/viewer-3d/CLAUDE.md) ``` Per-site files can override or extend global rules. --- ## `.credentials/` Centralized credential store at `sites/.credentials/`. | File | Purpose | |------|---------| | `manifest.json` | Auto-generated index of all credentials | | `refresh.ps1` | PowerShell script to regenerate the manifest | | `_netrc` | Basic auth credentials for HostGo domains (used with `curl --netrc-file`) | | `{domain}.json` | Basic auth: `{"host", "port", "user", "pass"}` | | `{name}-token.txt` | Bearer token (plain text, one line) | 28 credentials total. Two auth systems: 1. **HostGo/cPanel** -- basic auth via `_netrc`, port 2078 2. **Acequia Nephele** -- Bearer token via `-H "Authorization: Bearer $(cat ...)"`, ports 3334 or 443 The manifest distinguishes them by `type`: ```json { "waldo-webdav-token": { "type": "token", "file": "waldo-webdav-token.txt" }, "guerin.acequia.io": { "type": "basic", "file": "guerin.acequia.io.json", "host": "guerin.acequia.io", "port": 2078 } } ``` --- ## `.site` Files Route configuration for remote access. Found in 5 domain folders. ```yaml domain: waldo.webdav.acequia.io routes: webdav: type: webdav url: https://waldo.webdav.acequia.io:3334 auth: token credential: waldo-webdav-token default_route: webdav sync: local: / remote: / commands: get: Fetch file from remote (WebDAV GET) put: Upload file to remote (WebDAV PUT) mkdir: Create directory (WebDAV MKCOL) ls: List directory (WebDAV PROPFIND) rm: Delete file/dir (WebDAV DELETE) ``` The `credential` field references a key in `.credentials/manifest.json`. --- ## Domain Inventory 30+ domain folders. Categories: | Category | Examples | |----------|----------| | HostGo primary | acequia.io, redfish.com, simtable.com, anysurface.com, realtime.earth | | HostGo add-on | guerin.acequia.io, benperry.acequia.io, harvardviz.live, geo.camera | | Nephele WebDAV | waldo.webdav.acequia.io, stigmergic.webdav.acequia.io, simtable.acequia.io | | GitHub Pages | agentscript.org | | Local network | localhost, caminoiris.stephenguerin.com | --- ## How It All Connects When Claude opens a session in `sites/`: 1. **`CLAUDE.md`** is loaded as project instructions (global rules, credential protocol, writing style) 2. **`~/.claude/projects/.../memory/MEMORY.md`** is injected into the system prompt (persistent cross-session notes) 3. **`sites/.claude/settings.json`** sets workspace permissions 4. If working in a subdomain folder, that folder's **`CLAUDE.md`** and **`.ai/`** are also consulted 5. **`.credentials/manifest.json`** is the lookup table for any auth operation 6. **`.site`** files define how to reach remote servers The result: Claude has full context for any domain in the workspace, knows which auth method to use, follows consistent code and writing style, and keeps a local-first workflow with explicit remote sync.