feat(docs): publish the docs site from this repository at /refract/

.github/workflows/docs-deploy.yml

@@ -0,0 +1,51 @@
+name: Deploy docs site
+
+# Publishes apps/docs to this repository's GitHub Pages site,
+# https://refract-org.github.io/refract/. The site used to deploy from the
+# refract-docs repository at /refract-docs/; that address now serves a
+# redirect-only site pointing each old page at its new one.
+on:
+  push:
+    branches: [main]
+    paths:
+      - apps/docs/**
+      - .github/workflows/docs-deploy.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3.14"
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - run: bun install --frozen-lockfile
+      - run: bun run build
+        working-directory: apps/docs
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: apps/docs/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - id: deploy
+        uses: actions/deploy-pages@v5

AGENTS.md

@@ -45,7 +45,7 @@ bun run lint       # biome lint packages/
 - **packages/cli**: CLI tool (`refract` command)
 - **packages/persistence**: SQLite storage (bun:sqlite)
 - **packages/eval**: Evaluation harness
-- **apps/docs**: Public documentation site (CC-BY-4.0). Private workspace; `bun run lint|test|build` from its directory; CI is `docs-site.yml`.
+- **apps/docs**: Public documentation site (CC-BY-4.0), published to https://refract-org.github.io/refract/ by `docs-deploy.yml`. Private workspace; `bun run lint|test|build` from its directory; CI is `docs-site.yml`.
 - **apps/ui**: Browser-only file viewer. Private workspace that imports evidence-graph's event types as types only; CI is `viewer.yml`, which also runs on evidence-graph and `docs/examples` changes.
 
 The root `bun run test` and `bun run lint` cover `packages/` only; each app has its own `AGENTS.md`.

ARCHITECTURE.md

@@ -75,7 +75,7 @@ On Wikipedia the ground truth is RFC closures and ArbCom decisions; on fandom
 wikis it's talk-page-archived consensus with revision links to the exact edit
 that implemented the decision.
 
-![Architecture Data Flow](https://refract-org.github.io/refract-docs/architecture-flow.svg)
+![Architecture Data Flow](https://refract-org.github.io/refract/architecture-flow.svg)
 
 ## Data Flow (Text)
 

CHANGELOG.md

@@ -9,6 +9,7 @@
 - **The docs site and the viewer are checked in CI.** Since #37 imported them into `apps/docs` and `apps/ui`, nothing ran their lint, tests or builds: their workflows sat under `apps/*/.github`, which GitHub does not read, and the root suite excludes `apps/`. `docs-site.yml` and `viewer.yml` now run each app's checks, path-filtered and separate from the engine gate. The viewer's also runs when `packages/evidence-graph` or `docs/examples` change.
 
 ### Changed
+- **The docs site moved to https://refract-org.github.io/refract/.** It is built and published from `apps/docs` by `docs-deploy.yml`, so a change to the engine and to its documentation can land in one PR. Every page under the old address, https://refract-org.github.io/refract-docs/, redirects to the same page at the new one, and the old images stay where they were. Canonical URLs, Open Graph tags and the sitemap use the new address, as do the "Next steps" that `refract analyze` prints and the package READMEs.
 - **The apps use the monorepo's tooling.** Their own lockfiles (two `bun.lock`, one `package-lock.json`), `.husky` hooks, `mise.toml` and `prepare: husky` scripts are removed; the root lockfile, hook and toolchain cover them, and each app's `.lintstagedrc.json` still applies to its files. Their `package.json` repository and issue links point at this repository.
 
 ### Fixed

CONTRIBUTING.md

@@ -6,7 +6,7 @@
 2. **Run the gate**: `bun run build && bun run typecheck && bun run test` — all must pass before you start
 3. **Pick a task**: [Good first issues](https://github.com/refract-org/refract/labels/good%20first%20issue) are scoped for new contributors. The [workqueue](.github/workqueue/) has `ready` tasks.
 4. **Read the architecture**: [ARCHITECTURE.md](./ARCHITECTURE.md) — 5 minutes, saves hours of wrong turns
-5. **Build a custom analyzer**: [Tutorial](https://refract-org.github.io/refract-docs/tutorials/custom-analyzer/) steps through the full cycle
+5. **Build a custom analyzer**: [Tutorial](https://refract-org.github.io/refract/tutorials/custom-analyzer/) steps through the full cycle
 6. **Run `bun run ci` before opening a PR**: build + lint + typecheck + boundaries + test. All must pass.
 
 ### What packages need what

README.md

@@ -227,7 +227,7 @@ These build on the core engine:
 
 | Project | Purpose |
 |---------|---------|
-| [Docs site](./apps/docs) | Public documentation site — [integrations](https://refract-org.github.io/refract-docs/integrations/), quickstart, CLI, SDK, tutorials |
+| [Docs site](./apps/docs) | Public documentation site — [integrations](https://refract-org.github.io/refract/integrations/), quickstart, CLI, SDK, tutorials |
 | [Viewer](./apps/ui) | Browser-only file viewer — load JSONL, render timelines, diffs, citations |
 | [Demo data](./demo-data) | Local datasets; the [offline walkthrough](./docs/recipes.md#try-the-offline-walkthrough) uses a fictional library history |
 | [refract-py](https://github.com/refract-org/refract-py) | Python adapter — calls the CLI and returns dataclasses or DataFrames |

apps/docs/AGENTS.md

@@ -17,7 +17,7 @@ bun run test         # Vitest (verifies docs compile)
 - **Linter/Formatter:** Biome
 - **Tests:** Vitest
 - **Pre-commit:** the repository root's Husky hook runs lint-staged, which uses this directory's `.lintstagedrc.json`
-- **CI:** `.github/workflows/docs-site.yml` at the repository root
+- **CI:** `.github/workflows/docs-site.yml` at the repository root; `docs-deploy.yml` publishes `main` to https://refract-org.github.io/refract/
 - **Commit style:** Conventional Commits
 
 ## Verification

apps/docs/README.md

@@ -4,15 +4,15 @@ Public documentation for [Refract](https://github.com/refract-org/refract), a de
 
 ---
 
-**Live at:** [refract-org.github.io/refract-docs](https://refract-org.github.io/refract-docs/)
+**Live at:** [refract-org.github.io/refract](https://refract-org.github.io/refract/)
 
 ## Quick start
 
 ```bash
 npx @refract-org/cli analyze "Earth" --depth brief
 ```
 
-See [quickstart](https://refract-org.github.io/refract-docs/quickstart/) for a full walkthrough.
+See [quickstart](https://refract-org.github.io/refract/quickstart/) for a full walkthrough.
 
 ## Packages
 

apps/docs/assets/docs.js

@@ -113,7 +113,7 @@ let selectedIndex = -1;
 let currentResults = [];
 
 // Base path retrieved from global config
-const BASE = window.REFRACT_BASE || "/refract-docs/";
+const BASE = window.REFRACT_BASE || "/refract/";
 
 async function loadSearchIndex() {
 	if (indexLoaded) return;

apps/docs/build.mjs

@@ -10,11 +10,11 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const DOCS_DIR = join(__dirname, "docs");
 const DIST_DIR = join(__dirname, "dist");
 const ASSETS_DIR = join(__dirname, "assets");
-const BASE = process.env.BASE || "/refract-docs/";
+const BASE = process.env.BASE || "/refract/";
 // Absolute address of the published site. Canonical URLs, og:url, JSON-LD
 // and the sitemap point here even when BASE is overridden for a local build.
 const SITE_URL = (
-	process.env.SITE_URL || "https://refract-org.github.io/refract-docs/"
+	process.env.SITE_URL || "https://refract-org.github.io/refract/"
 ).replace(/\/?$/, "/");
 const SITE_NAME = "Refract";
 const SITE_DESCRIPTION =

apps/docs/package.json

@@ -10,7 +10,7 @@
 		"url": "git+https://github.com/refract-org/refract.git",
 		"directory": "apps/docs"
 	},
-	"homepage": "https://refract-org.github.io/refract-docs/",
+	"homepage": "https://refract-org.github.io/refract/",
 	"bugs": {
 		"url": "https://github.com/refract-org/refract/issues"
 	},

apps/docs/tests/links.test.ts

@@ -10,7 +10,7 @@ import { rewriteLink } from "../build.mjs";
 const ROOT_DIR = resolve(__dirname, "..");
 const DOCS_DIR = join(ROOT_DIR, "docs");
 const DIST_DIR = join(ROOT_DIR, "dist");
-const SITE_BASE = "/refract-docs";
+const SITE_BASE = "/refract";
 const SITE_URL = `https://refract-org.github.io${SITE_BASE}/`;
 const execFileAsync = promisify(execFile);
 
@@ -213,7 +213,7 @@ function escapeRegExp(value: string): string {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
-// The URL path a link in a built page points at ("/refract-docs/cli/"), or
+// The URL path a link in a built page points at ("/refract/cli/"), or
 // null for an external link or a same-page anchor. Absolute links to the
 // published site, such as the canonical URL, count as internal.
 function sitePathOf(sourceFile: string, href: string): string | null {
@@ -364,45 +364,45 @@ describe("Generated site links", async () => {
 
 describe("rewriteLink", () => {
 	it.each([
-		["cli", "", "/refract-docs/cli/"],
-		["./cli", "", "/refract-docs/cli/"],
-		["cli/", "", "/refract-docs/cli/"],
-		["cli.md", "", "/refract-docs/cli/"],
+		["cli", "", "/refract/cli/"],
+		["./cli", "", "/refract/cli/"],
+		["cli/", "", "/refract/cli/"],
+		["cli.md", "", "/refract/cli/"],
 		[
 			"schema#version-compatibility",
 			"",
-			"/refract-docs/schema/#version-compatibility",
+			"/refract/schema/#version-compatibility",
 		],
 		[
 			"schema.md#version-compatibility",
 			"",
-			"/refract-docs/schema/#version-compatibility",
+			"/refract/schema/#version-compatibility",
 		],
-		["tutorials/refract-ui", "", "/refract-docs/tutorials/refract-ui/"],
-		["fandom-canon.md", "tutorials", "/refract-docs/tutorials/fandom-canon/"],
-		["../analytics.md", "tutorials", "/refract-docs/analytics/"],
-		["../index.md", "tutorials", "/refract-docs/"],
-		["index.md", "", "/refract-docs/"],
-		["./", "", "/refract-docs/"],
-		["/quickstart", "tutorials", "/refract-docs/quickstart/"],
-		["cli?x=1", "", "/refract-docs/cli/?x=1"],
+		["tutorials/refract-ui", "", "/refract/tutorials/refract-ui/"],
+		["fandom-canon.md", "tutorials", "/refract/tutorials/fandom-canon/"],
+		["../analytics.md", "tutorials", "/refract/analytics/"],
+		["../index.md", "tutorials", "/refract/"],
+		["index.md", "", "/refract/"],
+		["./", "", "/refract/"],
+		["/quickstart", "tutorials", "/refract/quickstart/"],
+		["cli?x=1", "", "/refract/cli/?x=1"],
 	])("links %s (from docs/%s) to the page URL %s", (href, dir, expected) => {
 		expect(rewriteLink(href, dir)).toBe(expected);
 	});
 
 	it.each([
-		["mcp-sequence.svg", "", "/refract-docs/mcp-sequence.svg"],
+		["mcp-sequence.svg", "", "/refract/mcp-sequence.svg"],
 		[
 			"assets/refract-ui-screenshot.png",
 			"",
-			"/refract-docs/assets/refract-ui-screenshot.png",
+			"/refract/assets/refract-ui-screenshot.png",
 		],
 		[
 			"notebooks/model-evaluation.ipynb",
 			"",
-			"/refract-docs/notebooks/model-evaluation.ipynb",
+			"/refract/notebooks/model-evaluation.ipynb",
 		],
-		["../boundary.svg", "tutorials", "/refract-docs/boundary.svg"],
+		["../boundary.svg", "tutorials", "/refract/boundary.svg"],
 	])(
 		"leaves the asset link %s (from docs/%s) without a slash",
 		(href, dir, expected) => {

apps/docs/tests/seo.test.ts

@@ -15,7 +15,7 @@ import {
 
 const ROOT_DIR = resolve(__dirname, "..");
 const DIST_DIR = join(ROOT_DIR, "dist");
-const SITE_URL = "https://refract-org.github.io/refract-docs/";
+const SITE_URL = "https://refract-org.github.io/refract/";
 const SITE_DESCRIPTION =
 	"A deterministic observation engine for revision histories. It reads a page's edits and emits a typed event for each change.";
 // Pages that use the site description: the home page by design, and pages with
@@ -366,7 +366,7 @@ describe("social card", () => {
 		const png = renderSocialCard({
 			name: "Refract",
 			description,
-			address: "refract-org.github.io/refract-docs",
+			address: "refract-org.github.io/refract",
 		});
 		expect(pngSize(Buffer.from(png))).toEqual({ width: 1200, height: 630 });
 	});

apps/ui/README.md

@@ -53,4 +53,4 @@ Then drag `bitcoin-events.jsonl` onto the Refract UI upload zone.
 
 ---
 
-[Refract Engine](https://github.com/refract-org/refract) · [Docs](https://refract-org.github.io/refract-docs/) · [npm](https://www.npmjs.com/org/refract-org)
+[Refract Engine](https://github.com/refract-org/refract) · [Docs](https://refract-org.github.io/refract/) · [npm](https://www.npmjs.com/org/refract-org)

docs/repositories.md

@@ -13,10 +13,12 @@ adapter provide optional ways to consume its output.
 | `refract` `apps/ui/` | Browser-only file viewer | NDJSON events; event types imported from `@refract-org/evidence-graph` | `viewer.yml`: `bun run lint`, `bun run test` (with the engine contract), `bun run build` |
 | [refract-py](https://github.com/refract-org/refract-py) | Python subprocess adapter and notebook integrations | CLI flags and NDJSON output | `hatch test`, `hatch build` |
 
-The docs site still deploys from the [refract-docs](https://github.com/refract-org/refract-docs)
-repository, whose source was imported into `apps/docs/` with its history; the
-[refract-ui](https://github.com/refract-org/refract-ui) source was imported into
-`apps/ui/` the same way. Neither old repository has changed since the import.
+The docs site deploys from this repository (`docs-deploy.yml`) to
+<https://refract-org.github.io/refract/>. The [refract-docs](https://github.com/refract-org/refract-docs)
+and [refract-ui](https://github.com/refract-org/refract-ui) sources were imported
+into `apps/docs/` and `apps/ui/` with their history. refract-docs now publishes
+only a redirect site, which sends each `/refract-docs/` page to the same page
+under `/refract/`.
 
 This inventory was checked on 2026-10-12. The organization has no current
 `refract-labs` or `refract-demo-data` repository. Datasets live in `demo-data/`;
@@ -78,8 +80,10 @@ tested; repository consolidation does not require a simultaneous toolchain move.
    tutorial and asset paths. Build and preview the complete site before changing
    deployment. Preserve `/refract-docs/` URLs through an explicit redirect or
    deployment arrangement, including deep links, search, sitemap, and images.
-   *Status:* history imported (#37); lint, tests and build run in `docs-site.yml`.
-   Deployment has not moved, and reference pages are not yet mapped to `docs/`.
+   *Status:* history imported (#37); lint, tests and build run in `docs-site.yml`;
+   `docs-deploy.yml` publishes to `/refract/`, and refract-docs serves a page at
+   every old path that redirects to the new one, plus copies of the old images
+   and a catch-all for anything else. Reference pages are not yet mapped to `docs/`.
 2. **Move the viewer.** Import its history under `apps/ui/`, preserve its
    license, and keep its browser-only operation. Replace independently
    maintained event lists with a checked schema fixture or type-only adapter;

packages/analyzers/README.md

@@ -70,4 +70,4 @@ const ids = events.map((e) => createEventIdentity(e));
 
 For everything `refract analyze` prints, add `buildPageMoveEvents(windowPageMoves(...))` before and `correlateTalkRevisions(revisions, talkRevisions)` after `buildRevisionEvents`, then annotate all of them together.
 
-[Refract](https://github.com/refract-org/refract) · [Docs](https://github.com/refract-org/refract-docs) · [npm](https://www.npmjs.com/package/@refract-org/analyzers)
+[Refract](https://github.com/refract-org/refract) · [Docs](https://refract-org.github.io/refract/) · [npm](https://www.npmjs.com/package/@refract-org/analyzers)

packages/cli/README.md

@@ -45,4 +45,4 @@ refract diff --wiki-a https://starwars.fandom.com/api.php --wiki-b https://memor
 refract eval
 ```
 
-[Refract](https://github.com/refract-org/refract) · [Docs](https://github.com/refract-org/refract-docs) · [npm](https://www.npmjs.com/package/@refract-org/cli)
+[Refract](https://github.com/refract-org/refract) · [Docs](https://refract-org.github.io/refract/) · [npm](https://www.npmjs.com/package/@refract-org/cli)

packages/cli/src/index.ts

@@ -202,7 +202,7 @@ analyzeCmd.action(async (page, opts) => {
     );
     console.log(dim(`  Monitor for changes → refract cron pages.txt --interval 24 --notify-slack`));
     console.log(dim(`  Connect an AI    → refract mcp`));
-    console.log(dim(`  Full docs        → https://refract-org.github.io/refract-docs`));
+    console.log(dim(`  Full docs        → https://refract-org.github.io/refract/`));
   }
 });
 

packages/eval/README.md

@@ -28,4 +28,4 @@ bun add @refract-org/eval
 import { createEvalHarness, validateAgainstGroundTruth } from "@refract-org/eval";
 ```
 
-[Refract](https://github.com/refract-org/refract) · [Docs](https://github.com/refract-org/refract-docs) · [npm](https://www.npmjs.com/package/@refract-org/eval)
+[Refract](https://github.com/refract-org/refract) · [Docs](https://refract-org.github.io/refract/) · [npm](https://www.npmjs.com/package/@refract-org/eval)

packages/evidence-graph/README.md

@@ -37,4 +37,4 @@ import type { EvidenceEvent, Revision } from "@refract-org/evidence-graph";
 import { createClaimIdentity, createVerificationBundle } from "@refract-org/evidence-graph";
 ```
 
-[Refract](https://github.com/refract-org/refract) · [Docs](https://github.com/refract-org/refract-docs) · [npm](https://www.npmjs.com/package/@refract-org/evidence-graph)
+[Refract](https://github.com/refract-org/refract) · [Docs](https://refract-org.github.io/refract/) · [npm](https://www.npmjs.com/package/@refract-org/evidence-graph)

packages/ingestion/README.md

@@ -35,4 +35,4 @@ import { GitRevisionSource, MediaWikiClient, RateLimiter } from "@refract-org/in
 import type { RevisionFetcher, RevisionOptions } from "@refract-org/ingestion";
 ```
 
-[Refract](https://github.com/refract-org/refract) · [Docs](https://github.com/refract-org/refract-docs) · [npm](https://www.npmjs.com/package/@refract-org/ingestion)
+[Refract](https://github.com/refract-org/refract) · [Docs](https://refract-org.github.io/refract/) · [npm](https://www.npmjs.com/package/@refract-org/ingestion)

packages/persistence/README.md

@@ -21,4 +21,4 @@ import { Persistence } from "@refract-org/persistence";
 import type { PersistenceAdapter, PersistenceConfig } from "@refract-org/persistence";
 ```
 
-[Refract](https://github.com/refract-org/refract) · [Docs](https://github.com/refract-org/refract-docs)
+[Refract](https://github.com/refract-org/refract) · [Docs](https://refract-org.github.io/refract/)