docs: free documentation site (Docusaurus on GitHub Pages)

.github/workflows/docs.yml

@@ -0,0 +1,63 @@
+name: Deploy Docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'website/**'
+      - 'README.md'
+      - 'CHANGELOG.md'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: website/package-lock.json
+
+      - name: Install dependencies
+        working-directory: website
+        run: npm ci
+
+      - name: Build
+        working-directory: website
+        run: npm run build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: website/build
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -48,7 +48,15 @@
 # Local Codex security-scan artifacts (not part of the project)
 .codex-security-scans/
 /docs/superpowers
+
+# Docusaurus website — generated/installed dirs must not be committed
+/website/node_modules/
+/website/build/
+/website/.docusaurus/
 # Real-memory exports must never land in this PUBLIC repo — they belong in
 # the private kimetsu-bench repo, reviewed before commit (memories can carry
 # environment/work context).
 memories-export*.json
+
+# Generated by website/scripts/sync-docs.mjs (do not edit; edit docs/ instead)
+docs-site-content/

crates/kimetsu-brain/src/projector.rs

@@ -44,13 +44,20 @@ pub fn rebuild_in_place(conn: &Connection) -> KimetsuResult<usize> {
 }
 
 /// Read all stored events from the durable `events` table, ordered by
-/// (ts, event_id) so replay is deterministic and causal.
+/// (ts, rowid) so replay is deterministic AND causal.
+///
+/// `rowid` is the implicit, insertion-monotonic key, so within an equal `ts`
+/// it preserves append order — the true causal order (e.g. a `memory.cited`
+/// appended before the `memory.superseded` that reassigns it). The previous
+/// `event_id` tiebreak was NOT causal: event ids are ULIDs whose ordering is
+/// only random-tail-stable within the same millisecond, so equal-`ts` events
+/// replayed in a platform-dependent order — non-deterministic rebuilds.
 fn read_events_ordered(conn: &Connection) -> KimetsuResult<Vec<Event>> {
     let mut stmt = conn.prepare(
         "
         SELECT event_id, run_id, ts, kind, schema_version, payload_json
         FROM events
-        ORDER BY ts, event_id
+        ORDER BY ts, rowid
         ",
     )?;
     let rows = stmt.query_map([], |row| {

website/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

website/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+## Installation
+
+```bash
+yarn
+```
+
+## Local Development
+
+```bash
+yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+## Build
+
+```bash
+yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+## Deployment
+
+Using SSH:
+
+```bash
+USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```bash
+GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

website/docusaurus.config.js

@@ -0,0 +1,133 @@
+// @ts-check
+import {themes as prismThemes} from 'prism-react-renderer';
+
+/** @type {import('@docusaurus/types').Config} */
+const config = {
+  title: 'Kimetsu',
+  tagline: 'Proactive memory for AI coding agents',
+  favicon: 'img/favicon.ico',
+
+  future: {
+    v4: true,
+  },
+
+  url: 'https://rodcor.github.io',
+  baseUrl: '/kimetsu/',
+  trailingSlash: false,
+
+  organizationName: 'RodCor',
+  projectName: 'kimetsu',
+
+  onBrokenLinks: 'warn',
+
+  markdown: {
+    format: 'detect',
+    hooks: {
+      onBrokenMarkdownLinks: 'warn',
+    },
+  },
+
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+  },
+
+  presets: [
+    [
+      'classic',
+      /** @type {import('@docusaurus/preset-classic').Options} */
+      ({
+        docs: {
+          sidebarPath: './sidebars.js',
+          // Point at the repo's docs folder (one level up from website/)
+          path: '../docs-site-content',
+          editUrl: 'https://github.com/RodCor/kimetsu/edit/main/',
+          exclude: ['superpowers/**', '**/superpowers/**'],
+        },
+        blog: false,
+        theme: {
+          customCss: './src/css/custom.css',
+        },
+      }),
+    ],
+  ],
+
+  themeConfig:
+    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
+    ({
+      image: 'img/kimetsu-logo.png',
+      colorMode: {
+        defaultMode: 'dark',
+        respectPrefersColorScheme: false,
+      },
+      navbar: {
+        title: 'Kimetsu',
+        logo: {
+          alt: 'Kimetsu logo',
+          src: 'img/kimetsu-logo.png',
+        },
+        items: [
+          {
+            type: 'docSidebar',
+            sidebarId: 'docsSidebar',
+            position: 'left',
+            label: 'Docs',
+          },
+          {
+            href: 'https://github.com/RodCor/kimetsu',
+            label: 'GitHub',
+            position: 'right',
+          },
+          {
+            href: 'https://crates.io/crates/kimetsu-cli',
+            label: 'crates.io',
+            position: 'right',
+          },
+          {
+            href: 'https://www.npmjs.com/package/kimetsu-ai',
+            label: 'npm',
+            position: 'right',
+          },
+        ],
+      },
+      footer: {
+        style: 'dark',
+        links: [
+          {
+            title: 'Docs',
+            items: [
+              {label: 'Introduction', to: '/docs/intro'},
+              {label: 'Install', to: '/docs/install'},
+              {label: 'How it works', to: '/docs/how-kimetsu-works'},
+              {label: 'Changelog', to: '/docs/changelog'},
+            ],
+          },
+          {
+            title: 'Links',
+            items: [
+              {
+                label: 'GitHub',
+                href: 'https://github.com/RodCor/kimetsu',
+              },
+              {
+                label: 'crates.io',
+                href: 'https://crates.io/crates/kimetsu-cli',
+              },
+              {
+                label: 'npm',
+                href: 'https://www.npmjs.com/package/kimetsu-ai',
+              },
+            ],
+          },
+        ],
+        copyright: `Copyright © ${new Date().getFullYear()} Kimetsu contributors. Built with Docusaurus.`,
+      },
+      prism: {
+        theme: prismThemes.github,
+        darkTheme: prismThemes.dracula,
+        additionalLanguages: ['bash', 'toml', 'rust'],
+      },
+    }),
+};
+
+export default config;