docs: scaffold Vite + Tailwind one-page docs site

Ports BunsDev/comux's docs architecture to coven-code: Vite 6 +
Tailwind 4 + @cloudflare/vite-plugin, single-page layout with a
floating sidebar and IntersectionObserver scroll-spy, hero with
animated logo / install command / GitHub stars badge, content
registry of per-section render() modules, and a Cloudflare Worker
that proxies /api/stars with edge caching.

Accent palette swapped from comux purple (#8b5cf6) to coven pink
(#E91E63) family across the theme tokens, hero glow, code-block
border, and syntax highlighting.

Initial content modules port six of the existing docs/*.md pages
(introduction, getting-started, welcome-screen, configuration,
providers, familiars); the remaining .md files can be added by
dropping new modules into src/content/ and registering them in
src/content/index.js.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: BunsDev

docs/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "coven-code-docs",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build && rm -rf client && cp -R src/dist/client client",
+    "preview": "vite build && vite preview",
+    "deploy": "vite build && wrangler deploy -c wrangler.json"
+  },
+  "devDependencies": {
+    "@cloudflare/vite-plugin": "1.25.1",
+    "@tailwindcss/vite": "4.1.18",
+    "tailwindcss": "4.1.18",
+    "vite": "6.4.2",
+    "wrangler": "4.66.0"
+  }
+}

docs/public/coven.svg

@@ -0,0 +1,19 @@
+export const GITHUB_STARS_API = 'https://api.github.com/repos/OpenCoven/coven-code';
+export const GITHUB_STARS_ACCEPT = 'application/vnd.github.v3+json';
+export const STARS_CACHE_TTL_SECONDS = 60;
+export const STARS_STALE_REVALIDATE_SECONDS = STARS_CACHE_TTL_SECONDS * 5;
+
+export function parseGithubStarCount(data) {
+  const count = data?.stargazers_count;
+  return typeof count === 'number' ? count : null;
+}
+
+export async function fetchGithubStarCount(fetchImpl = fetch, userAgent = 'coven-code-docs') {
+  const headers = { Accept: GITHUB_STARS_ACCEPT };
+  if (userAgent) headers['User-Agent'] = userAgent;
+
+  const response = await fetchImpl(GITHUB_STARS_API, { headers });
+  if (!response.ok) return null;
+
+  return parseGithubStarCount(await response.json());
+}

docs/public/favicon.svg

@@ -0,0 +1,115 @@
+/**
+ * Lightweight syntax highlighting and copy-to-clipboard for code blocks.
+ * Uses token placeholders to prevent regex passes from corrupting each other.
+ */
+
+const KEYWORDS = /\b(const|let|var|function|return|if|else|for|while|class|import|export|from|default|async|await|new|this|try|catch|throw|typeof|interface|type|extends|implements|enum|readonly|true|false|null|undefined|void|string|number|boolean|fn|pub|mut|impl|trait|struct|enum|match|use|mod|crate|self|Self|where|move|ref|box|as)\b/g;
+const STRINGS = /(["'`])(?:(?=(\\?))\2.)*?\1/g;
+const COMMENTS = /(\/\/.*$|\/\*[\s\S]*?\*\/)/gm;
+const NUMBERS = /\b(\d+\.?\d*)\b/g;
+const FUNCTIONS = /\b([a-zA-Z_]\w*)\s*(?=\()/g;
+const SHELL_COMMENT = /^(\s*#.*)$/gm;
+const SHELL_CMD = /^(\s*)(npm|npx|pnpm|yarn|curl|git|cd|mkdir|cat|echo|tmux|comux|coven-code|coven|cargo|rustup|ls|rm|cp|mv|sudo|brew|apt|pip|node|deno|bun|chmod|export)\b/gm;
+const SHELL_FLAG = /\s(--?[\w-]+)/g;
+const JSON_KEY = /("[\w-]+")\s*:/g;
+
+function escapeHtml(str) {
+  return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+function tok(text, regex, cls, tokens) {
+  return text.replace(regex, (match) => {
+    const i = tokens.length;
+    tokens.push(`<span class="${cls}">${match}</span>`);
+    return `\x00${i}\x00`;
+  });
+}
+
+function restore(text, tokens) {
+  return text.replace(/\x00(\d+)\x00/g, (_, i) => tokens[i]);
+}
+
+function highlightJS(code) {
+  const tokens = [];
+  let r = escapeHtml(code);
+  r = tok(r, COMMENTS, 'hl-comment', tokens);
+  r = tok(r, STRINGS, 'hl-string', tokens);
+  r = tok(r, KEYWORDS, 'hl-keyword', tokens);
+  r = tok(r, NUMBERS, 'hl-number', tokens);
+  r = tok(r, FUNCTIONS, 'hl-fn', tokens);
+  return restore(r, tokens);
+}
+
+function highlightShell(code) {
+  const tokens = [];
+  let r = escapeHtml(code);
+  r = tok(r, SHELL_COMMENT, 'hl-comment', tokens);
+  r = tok(r, STRINGS, 'hl-string', tokens);
+  r = r.replace(SHELL_CMD, (match, ws, cmd) => {
+    const i = tokens.length;
+    tokens.push(`<span class="hl-keyword">${cmd}</span>`);
+    return `${ws}\x00${i}\x00`;
+  });
+  r = r.replace(SHELL_FLAG, (match, flag) => {
+    const i = tokens.length;
+    tokens.push(`<span class="hl-fn">${flag}</span>`);
+    return ` \x00${i}\x00`;
+  });
+  return restore(r, tokens);
+}
+
+function highlightJSON(code) {
+  const tokens = [];
+  let r = escapeHtml(code);
+  r = tok(r, STRINGS, 'hl-string', tokens);
+  r = r.replace(JSON_KEY, (match, key) => {
+    const i = tokens.length;
+    tokens.push(`<span class="hl-fn">${key}</span>`);
+    return `\x00${i}\x00:`;
+  });
+  r = tok(r, NUMBERS, 'hl-number', tokens);
+  r = tok(r, /\b(true|false|null)\b/g, 'hl-keyword', tokens);
+  return restore(r, tokens);
+}
+
+export function highlight(code, lang) {
+  if (!lang) lang = '';
+  lang = lang.toLowerCase().trim();
+  if (['bash', 'sh', 'shell', 'zsh'].includes(lang)) return highlightShell(code);
+  if (['json', 'jsonc'].includes(lang)) return highlightJSON(code);
+  if (['js', 'javascript', 'ts', 'typescript', 'jsx', 'tsx', 'rs', 'rust'].includes(lang)) return highlightJS(code);
+  return escapeHtml(code);
+}
+
+export function processCodeBlocks(container) {
+  container.querySelectorAll('pre code').forEach((block) => {
+    const lang = block.dataset.lang || '';
+    const raw = block.textContent;
+    block.innerHTML = highlight(raw, lang);
+
+    const pre = block.parentElement;
+    if (pre && !pre.querySelector('.code-copy')) {
+      const btn = document.createElement('button');
+      btn.className = 'code-copy';
+      btn.title = 'Copy to clipboard';
+      btn.innerHTML = `<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>`;
+      btn.addEventListener('click', () => {
+        navigator.clipboard.writeText(raw).then(() => {
+          btn.innerHTML = `<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="20 6 9 17 4 12"/></svg>`;
+          setTimeout(() => {
+            btn.innerHTML = `<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>`;
+          }, 2000);
+        });
+      });
+      pre.style.position = 'relative';
+      pre.appendChild(btn);
+    }
+
+    if (lang && !pre.querySelector('.code-lang')) {
+      const label = document.createElement('span');
+      label.className = 'code-lang';
+      label.textContent = lang;
+      pre.appendChild(label);
+    }
+  });
+}

docs/public/og.svg

@@ -0,0 +1,95 @@
+export const meta = { title: 'Configuration' };
+
+export function render() {
+  return `
+    <h1>Configuration</h1>
+    <p class="lead">Coven Code is configured through a layered system of JSON files, environment variables, and command-line flags. Project settings override global settings; CLI flags override both.</p>
+
+    <h2>File locations</h2>
+
+    <p>The global settings file lives at:</p>
+
+    <pre><code data-lang="bash">~/.coven-code/settings.json</code></pre>
+
+    <p>The directory is created automatically on first run. Files are standard JSON (or JSONC — comments are stripped before parsing).</p>
+
+    <h3>Per-project settings</h3>
+
+    <p>Coven Code walks up from the current working directory looking for a project-level settings file. The first file found wins:</p>
+
+    <pre><code data-lang="bash">&lt;project-root&gt;/.coven-code/settings.json
+&lt;project-root&gt;/.coven-code/settings.jsonc</code></pre>
+
+    <p>Keys present in the project file override the global value; keys absent fall back to global.</p>
+
+    <h2>Top-level structure</h2>
+
+    <pre><code data-lang="json">{
+  "version": 1,
+  "provider": "anthropic",
+  "config": { },
+  "providers": { },
+  "projects": { },
+  "commands": { },
+  "formatter": { },
+  "agents": { },
+  "skills": { },
+  "permissionRules": [],
+  "enabledPlugins": [],
+  "disabledPlugins": [],
+  "hasCompletedOnboarding": false
+}</code></pre>
+
+    <p>Most day-to-day options live inside the <code>config</code> object. Provider credentials live in the <code>providers</code> map.</p>
+
+    <h2>Common <code>config</code> options</h2>
+
+    <h3>Model and tokens</h3>
+    <table>
+      <thead><tr><th>Key</th><th>Default</th><th>Description</th></tr></thead>
+      <tbody>
+        <tr><td><code>api_key</code></td><td><code>null</code></td><td>Anthropic API key. Overrides <code>ANTHROPIC_API_KEY</code>. Prefer the env var in shared environments.</td></tr>
+        <tr><td><code>model</code></td><td>provider default</td><td>Model ID. Falls back to the provider's default (e.g. <code>claude-sonnet-4-6</code>).</td></tr>
+        <tr><td><code>max_tokens</code></td><td><code>8192</code></td><td>Maximum tokens per model response.</td></tr>
+        <tr><td><code>provider</code></td><td><code>"anthropic"</code></td><td>Active provider.</td></tr>
+      </tbody>
+    </table>
+
+    <h3>Permission mode</h3>
+    <table>
+      <thead><tr><th>Mode</th><th>Behavior</th></tr></thead>
+      <tbody>
+        <tr><td><code>default</code></td><td>Prompt for any tool that touches your filesystem or shell.</td></tr>
+        <tr><td><code>acceptEdits</code></td><td>Auto-approve file edits; still prompt for shell.</td></tr>
+        <tr><td><code>bypassPermissions</code></td><td>No prompts. Use only in trusted, sandboxed contexts.</td></tr>
+        <tr><td><code>plan</code></td><td>Read-only mode. Model can read and search but cannot write or run commands.</td></tr>
+      </tbody>
+    </table>
+
+    <h3>Familiar</h3>
+    <p>Set <code>"familiar"</code> to the id of your active familiar (e.g. <code>"kitty"</code>, <code>"raven"</code>). This drives the welcome-screen portrait and the <code>/agents</code> overlay when the daemon is online.</p>
+
+    <pre><code data-lang="json">{
+  "familiar": "raven",
+  "config": {
+    "model": "claude-opus-4-7",
+    "permission_mode": "default",
+    "auto_compact": true,
+    "compact_threshold": 0.8
+  }
+}</code></pre>
+
+    <h2>Environment variables</h2>
+
+    <table>
+      <thead><tr><th>Variable</th><th>Purpose</th></tr></thead>
+      <tbody>
+        <tr><td><code>ANTHROPIC_API_KEY</code></td><td>API key for Anthropic provider.</td></tr>
+        <tr><td><code>OPENAI_API_KEY</code></td><td>API key for OpenAI provider.</td></tr>
+        <tr><td><code>COVEN_CODE_HOME</code></td><td>Override the default <code>~/.coven-code/</code> directory.</td></tr>
+      </tbody>
+    </table>
+
+    <p>See <a href="https://github.com/OpenCoven/coven-code/blob/main/docs/configuration.md" target="_blank" rel="noopener">the full configuration reference</a> for every option, including <code>agents</code>, <code>commands</code>, <code>permissionRules</code>, and per-provider keys.</p>
+  `;
+}

docs/shared/githubStars.js

@@ -0,0 +1,80 @@
+export const meta = { title: 'Familiars' };
+
+export function render() {
+  return `
+    <h1>Coven familiars</h1>
+    <p class="lead">Coven Code integrates natively with the Coven daemon's familiar roster. When the daemon is installed and running, every familiar you have configured under <code>~/.coven/</code> is automatically available inside Coven Code as a selectable agent persona — no extra setup required.</p>
+
+    <h2>What is a familiar?</h2>
+
+    <p>A familiar is a named AI persona defined in the Coven ecosystem. Each familiar has an identity (display name, emoji, pronouns), a role description, and optional metadata used to shape how the model presents itself and reasons about tasks. Familiars are user-defined and live in <code>~/.coven/familiars.toml</code>, managed by the Coven daemon.</p>
+
+    <p>For example, a minimal Coven setup might have:</p>
+
+    <table>
+      <thead><tr><th>ID</th><th>Name</th><th>Role</th></tr></thead>
+      <tbody>
+        <tr><td><code>dev</code></td><td>Dev 🤖</td><td>Code-first implementation agent</td></tr>
+        <tr><td><code>research</code></td><td>Research 🧙</td><td>Research and reasoning</td></tr>
+        <tr><td><code>writer</code></td><td>Writer ✍️</td><td>Writing and communication</td></tr>
+      </tbody>
+    </table>
+
+    <p>You define your own familiars — the names, roles, and roster are entirely yours.</p>
+
+    <h2>How familiars appear</h2>
+
+    <p>When the daemon is present, <code>load_agent_definitions()</code> reads <code>~/.coven/familiars.toml</code> and converts each familiar into an <code>AgentDefinition</code> with:</p>
+
+    <ul>
+      <li><strong>source:</strong> <code>coven:familiar:&lt;id&gt;</code> — distinguishes them from user-defined agents</li>
+      <li><strong>instructions:</strong> a synthesised system-prompt body that captures the familiar's name, role, and description</li>
+      <li><strong>memory_scope:</strong> <code>workspace</code> — familiars have full workspace context by default</li>
+      <li><strong>model:</strong> inherits the session default (no override unless the user sets one)</li>
+    </ul>
+
+    <p>Familiars are appended <strong>after</strong> workspace agents in the list. If a user-defined agent shares the same display name as a familiar, the user definition wins.</p>
+
+    <h2>Where familiars show up</h2>
+
+    <ol>
+      <li>The <strong>welcome panel</strong> (top-left of the home screen): glyph, name, access tier dot, and on wider terminals the role and an accent rule. See <a href="#welcome-screen">Welcome Screen</a>.</li>
+      <li>The <strong>F2 switcher popup</strong>: one row per familiar, each painted in that familiar's accent palette with a coloured tier dot.</li>
+      <li>The <strong><code>/agents</code> detail view</strong>: the card appears above the persona preview when you select a familiar-sourced agent.</li>
+    </ol>
+
+    <h2>Switching familiars</h2>
+
+    <p>From the TUI, press <kbd>F2</kbd> to open the switcher, or use the slash command:</p>
+
+    <pre><code data-lang="bash">/familiar raven
+/familiar list</code></pre>
+
+    <p>From the CLI:</p>
+
+    <pre><code data-lang="bash">coven-code agents list
+coven-code agents use raven</code></pre>
+
+    <p>Or set it persistently in <code>~/.coven-code/settings.json</code>:</p>
+
+    <pre><code data-lang="json">{
+  "familiar": "raven"
+}</code></pre>
+
+    <h2>Without the daemon</h2>
+
+    <p>Coven Code works fully standalone. Without the daemon, familiars degrade gracefully:</p>
+
+    <ul>
+      <li>The welcome panel shows a built-in glyph (default: <code>kitty</code>).</li>
+      <li>The <code>/agents</code> overlay shows only workspace agents.</li>
+      <li><kbd>F2</kbd> opens a switcher with the bundled built-in familiars.</li>
+    </ul>
+
+    <p>Install the daemon to unlock the full roster:</p>
+
+    <pre><code data-lang="bash">npm install -g @opencoven/coven</code></pre>
+
+    <p>See <a href="https://github.com/OpenCoven/coven-code/blob/main/docs/familiars.md" target="_blank" rel="noopener">the full familiars reference</a> for access tiers, persona authoring, and CLI integration.</p>
+  `;
+}