docs: seed ADR catalogue

.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+      # Node 22 ships npm 10; the lockfile is generated by npm 11+ which
+      # handles transitive peer ranges (e.g. @types/react@18 pulled through
+      # dev deps) differently — npm 10 rejects with "package.json and
+      # package-lock.json not in sync." Avoid the global self-upgrade race
+      # ("Cannot find module 'promise-retry'") by shelling out to a pinned
+      # npm via npx.
+      - run: npx -y npm@11.12.1 ci
+      - run: npm run lint
+      - run: npx tsc --noEmit
+      - run: npm run test:release

.github/workflows/docs.yml

@@ -0,0 +1,75 @@
+name: Deploy docs site
+
+# Builds the VitePress site under .vitepress/ and publishes it to the
+# repo's GitHub Pages environment. Triggered on pushes to main that
+# touch docs sources (README, ARCHITECTURE, CONTRIBUTING, SECURITY,
+# docs/**, or the VitePress config itself), plus a manual dispatch for
+# republishing without a content change.
+#
+# Pages must be enabled on the repo with the "GitHub Actions" source
+# (Settings → Pages → Source: GitHub Actions) for the deploy step to
+# succeed. The published URL is https://vilaca.github.io/factory/.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'README.md'
+      - 'ARCHITECTURE.md'
+      - 'CONTRIBUTING.md'
+      - 'SECURITY.md'
+      - 'docs/**'
+      - '.vitepress/**'
+      - '.github/workflows/docs.yml'
+      - 'package.json'
+      - 'package-lock.json'
+  workflow_dispatch:
+
+# One in-flight deploy at a time; newer pushes preempt older ones so
+# the site reflects HEAD without queueing redundant builds.
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+      - name: Install dependencies
+        # --legacy-peer-deps: VitePress transitively depends on
+        # @docsearch/react, whose peer declares react < 19. The main
+        # project pins react@19 (used by Ink), which npm 10 (the version
+        # shipped with the setup-node@v4 / Node 22 combo) treats as a
+        # hard conflict and refuses to install. The peer is bogus in
+        # practice — VitePress doesn't actually mount @docsearch/react
+        # at runtime when `search.provider: 'local'` is configured (see
+        # .vitepress/config.ts) — so the legacy resolver is both safe
+        # and necessary here.
+        run: npm ci --legacy-peer-deps
+      - name: Build VitePress site
+        run: npm run docs:build
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: .vitepress/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -34,3 +34,8 @@ coverage/
 
 # Local-only scratch
 IDEAS.md
+
+# VitePress docs site build output + deps
+.vitepress/dist/
+.vitepress/cache/
+.vitepress/node_modules/

.vitepress/config.ts

@@ -0,0 +1,107 @@
+import { defineConfig } from 'vitepress';
+
+// VitePress site for factory. Reuses the existing repo markdown
+// (README.md, ARCHITECTURE.md, CONTRIBUTING.md, SECURITY.md, docs/*)
+// as the source of truth — this config only adds nav/sidebar wiring.
+//
+// Build: `npm --prefix .vitepress run build` produces .vitepress/dist/,
+// which the GH Action publishes to GitHub Pages at
+// https://vilaca.github.io/factory/.
+export default defineConfig({
+  // GH Pages serves the site under /factory/. Both the dev server and
+  // the built site must know this so internal links resolve correctly.
+  base: '/factory/',
+  title: 'factory',
+  description:
+    'A terminal-first coding agent. Self-hosted, provider-agnostic, configurable.',
+  cleanUrls: true,
+  lastUpdated: true,
+  // README links to relative paths like ./docs/providers.md and
+  // ./ARCHITECTURE.md. VitePress follows those at build time. The few
+  // exceptions — links to LICENSE (not markdown, served as a GitHub
+  // file), localhost, and similar — get ignored here rather than
+  // rewritten in the source README.
+  ignoreDeadLinks: [
+    // LICENSE is a plain-text file, not a markdown page. README's
+    // "see LICENSE" link is valid on GitHub but VitePress can't render
+    // it as a page. Users land on the GitHub copy either way.
+    /^\.?\/LICENSE$/i,
+    /^https?:\/\/localhost/,
+  ],
+  // README is the landing page; the rest hangs off the sidebar.
+  rewrites: {
+    'README.md': 'index.md',
+  },
+  // Skip files VitePress shouldn't try to render as pages.
+  srcExclude: [
+    'node_modules/**',
+    'dist/**',
+    'dist-test/**',
+    'coverage/**',
+    'src/**',
+    'test/**',
+    'scripts/**',
+    'CHANGELOG.md',
+    'IDEAS.md',
+  ],
+  themeConfig: {
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Quick start', link: '/#quick-start' },
+      { text: 'Docs', link: '/docs/configuration' },
+      { text: 'Architecture', link: '/ARCHITECTURE' },
+      { text: 'GitHub', link: 'https://github.com/vilaca/factory' },
+    ],
+    sidebar: [
+      {
+        text: 'Getting started',
+        items: [
+          { text: 'Overview', link: '/' },
+          { text: 'Configuration', link: '/docs/configuration' },
+          { text: 'Providers', link: '/docs/providers' },
+          { text: 'Troubleshooting', link: '/docs/troubleshooting' },
+        ],
+      },
+      {
+        text: 'Usage',
+        items: [
+          { text: 'Slash commands', link: '/docs/slash-commands' },
+          { text: 'Hotkeys', link: '/docs/hotkeys' },
+          { text: 'Headless mode', link: '/docs/headless' },
+          { text: 'WebFetch tool', link: '/docs/web-fetch' },
+          { text: 'Sampling params', link: '/docs/sampling-params' },
+        ],
+      },
+      {
+        text: 'Operations',
+        items: [
+          { text: 'Security', link: '/docs/security' },
+          { text: 'Observability', link: '/docs/observability' },
+          { text: 'Picker internals', link: '/docs/picker-internals' },
+        ],
+      },
+      {
+        text: 'Project',
+        items: [
+          { text: 'Architecture', link: '/ARCHITECTURE' },
+          { text: 'Contributing', link: '/CONTRIBUTING' },
+          { text: 'Security policy', link: '/SECURITY' },
+        ],
+      },
+    ],
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/vilaca/factory' },
+    ],
+    editLink: {
+      pattern: 'https://github.com/vilaca/factory/edit/main/:path',
+      text: 'Edit this page on GitHub',
+    },
+    search: {
+      provider: 'local',
+    },
+    footer: {
+      message: 'Released under the Apache-2.0 License.',
+      copyright: 'Copyright © vilaca',
+    },
+  },
+});

CONTRIBUTING.md

@@ -89,3 +89,7 @@ The project follows [Semantic Versioning](https://semver.org/). Pre-1.0, breakin
 ## Architecture overview
 
 See [ARCHITECTURE.md](ARCHITECTURE.md) for a full module map and data-flow walkthrough.
+
+## Architecture Decision Records
+
+Decisions that change an invariant in [ARCHITECTURE.md](ARCHITECTURE.md), `src/security/`, or the `core/agent/` loop require an ADR — see [docs/adr/README.md](docs/adr/README.md) for the catalogue, conventions, and template. Reference the ADR number in the PR description.

README.md

@@ -1,9 +1,10 @@
 # 🏭 factory
 
+[![CI](https://github.com/vilaca/factory/actions/workflows/ci.yml/badge.svg)](https://github.com/vilaca/factory/actions/workflows/ci.yml)
 ![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)
 ![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)
 
-**A coding agent that runs anywhere — local or cloud, frontier or 7B — with the resilience to make smaller models actually useful.**
+**A coding agent CLI engineered to make any LLM — local or cloud, frontier or 7B — actually useful.**
 
 ## Why factory
 
@@ -33,6 +34,8 @@ That's it. `factory` opens a picker for provider, model, and API key the first t
 
 > **`npm link` permission errors?** It writes a symlink into your npm global prefix; if that's a system path it needs sudo. Either set a user-writable prefix once (`npm config set prefix "$HOME/.npm-global"` and add `$HOME/.npm-global/bin` to your `PATH`), skip linking and run `npx factory` from the repo, or invoke directly with `node /path/to/factory/dist/index.js`.
 
+> **npm install coming soon.** A `factory-code` package will land on npm once the first tagged release ships; until then, build from source.
+
 ## Documentation
 
 - [docs/providers.md](./docs/providers.md) — full provider matrix, env vars, auth specifics
@@ -50,7 +53,7 @@ That's it. `factory` opens a picker for provider, model, and API key the first t
 ## Quick reference
 
 ```bash
-factory --version                                    # 0.1.0
+factory --version                                    # print version
 factory --help                                       # full flag list
 factory                                              # interactive picker
 factory -p anthropic -m claude-sonnet-4-6            # one-shot