docs

docs/README.md

@@ -1,30 +1,23 @@
 # Documentation Index
 
-Use this directory for project documentation outside `README.md` and `agents.md`.
+This directory contains both docs content and docs tooling.
 
-## Deploy
+## Audience-Based Structure
 
-- `docs/deploy/quickstart.md`: deployment modes, local dev startup, and quality command reference.
+- `docs/user/`: onboarding and usage-oriented docs for self-hosters.
+- `docs/operations/`: runbooks and rollout checklists for ongoing operations.
+- `docs/developer/`: architecture, contribution standards, and local development workflows.
+- `docs/reference/`: canonical API and environment contracts.
 
-## Reference
+## Docs Tooling
 
-- `docs/reference/environment.md`: complete environment-variable catalog and contract/audit notes.
-- `docs/reference/api_contract.md`: API envelope contract and endpoint semantics.
+- `docs/website/`: Docusaurus app used to publish docs to GitHub Pages.
 
-## Architecture
+## Recommended Reading Paths
 
-- `docs/architecture/domain_boundaries.md`: domain boundaries, user-scoped data rules, and frontend behavior notes.
+- Users: `docs/user/getting-started.md`
+- Operators: `docs/operations/overview.md`
+- Developers: `docs/developer/overview.md`
+- Contract consumers: `docs/reference/overview.md`
 
-## Operations
-
-- `docs/ops/scrape_safety_runbook.md`: scrape cooldown and blocked-IP operations.
-- `docs/ops/db_runbook.md`: backup, restore, and verification workflows.
-- `docs/ops/migration_checklist.md`: migration planning and rollout checklist.
-
-## Frontend
-
-- `docs/frontend/theme_phase0_inventory.md`: theme-token inventory and adoption notes.
-
-## Contribution
-
-- `docs/contributing.md`: contribution policy and merge checklist.
+Published site: https://justinzeus.github.io/scholarr/

docs/developer/documentation-standards.md

@@ -0,0 +1,26 @@
+# Documentation Standards
+
+This project keeps docs organized by audience and document type.
+
+## Audience Split
+
+- `user/`: onboarding and usage tasks for self-hosted users.
+- `operations/`: runbooks and checklists for production operation.
+- `developer/`: architecture, contribution workflow, and implementation guides.
+- `reference/`: stable contracts (API, env variables, configuration behavior).
+
+## Document Quality Rules
+
+- One primary audience per page.
+- Task pages must include prerequisites, exact commands, and verification steps.
+- Reference pages should be contract-first and avoid procedural noise.
+- Runbooks should include recovery steps and rollback/safety notes.
+- Prefer concise pages with strong cross-links over long mixed-purpose pages.
+
+## Required Top-Level Entrypoints
+
+- `index.md`: user/developer/operator navigation hub.
+- `user/getting-started.md`: first-run path.
+- `developer/local-development.md`: contributor setup and validation path.
+- `operations/overview.md`: operational playbook index.
+- `reference/overview.md`: contract index.

docs/developer/local-development.md

@@ -1,30 +1,6 @@
-# Deploy and Dev Quickstart
+# Developer Local Development
 
-## Required Setup
-
-1. Copy `.env.example` to `.env`.
-2. Set `POSTGRES_PASSWORD`.
-3. Set `SESSION_SECRET_KEY`.
-
-## Deploy Method A: Prebuilt Image
-
-```bash
-docker compose pull
-docker compose up -d
-```
-
-Open:
-- App/API: `http://localhost:8000`
-- Health endpoint: `http://localhost:8000/healthz`
-
-Upgrade:
-
-```bash
-docker compose pull
-docker compose up -d
-```
-
-## Deploy Method B: Local Source + Dev Frontend
+## Start the Dev Stack
 
 ```bash
 docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
@@ -40,16 +16,14 @@ Stop:
 docker compose -f docker-compose.yml -f docker-compose.dev.yml down
 ```
 
-## Quality Commands
-
-Backend:
+## Backend Validation
 
 ```bash
 docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm app uv run pytest tests/unit
 docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm app uv run pytest -m integration
 ```
 
-Frontend:
+## Frontend Validation
 
 ```bash
 cd frontend
@@ -59,10 +33,20 @@ npm run test:run
 npm run build
 ```
 
-Repository checks:
+## Repository Gates
 
 ```bash
 python3 scripts/check_frontend_api_contract.py
 python3 scripts/check_env_contract.py
 ./scripts/check_no_generated_artifacts.sh
 ```
+
+## Docs Site (Contributor Workflow)
+
+Docs tooling is colocated in `docs/website/`:
+
+```bash
+cd docs/website
+npm install
+npm run build
+```

docs/developer/overview.md

@@ -0,0 +1,9 @@
+# Developer Documentation
+
+Use this section if you are contributing code or running full quality gates.
+
+- [Documentation Standards](./documentation-standards.md)
+- [Local Development](./local-development.md)
+- [Architecture Boundaries](./architecture.md)
+- [Contributing](./contributing.md)
+- [Frontend Theme Inventory](./frontend-theme-inventory.md)

docs/index.md

@@ -4,9 +4,30 @@ slug: /
 
 # scholarr Documentation
 
-- Start here: `docs/deploy/quickstart.md`
-- Runtime config: `docs/reference/environment.md`
-- API contract: `docs/reference/api_contract.md`
-- Domain boundaries: `docs/architecture/domain_boundaries.md`
-- Ops runbooks: `docs/ops/`
-- Frontend theme inventory: `docs/frontend/theme_phase0_inventory.md`
+This documentation is organized for both users and developers.
+
+## For Users
+
+- [User Overview](./user/overview.md)
+- [Getting Started](./user/getting-started.md)
+
+## For Operators
+
+- [Operations Overview](./operations/overview.md)
+- [Scrape Safety Runbook](./operations/scrape-safety-runbook.md)
+- [Database Runbook](./operations/database-runbook.md)
+- [Migration Rollout Checklist](./operations/migration-checklist.md)
+
+## For Developers
+
+- [Developer Overview](./developer/overview.md)
+- [Local Development](./developer/local-development.md)
+- [Architecture Boundaries](./developer/architecture.md)
+- [Contributing](./developer/contributing.md)
+- [Frontend Theme Inventory](./developer/frontend-theme-inventory.md)
+
+## Reference
+
+- [Reference Overview](./reference/overview.md)
+- [API Contract](./reference/api-contract.md)
+- [Environment Reference](./reference/environment.md)

docs/operations/database-runbook.md

@@ -88,7 +88,7 @@ python3 scripts/db/repair_publication_links.py --user-id <id> --requested-by "<o
 
 Dry-run first, then re-run with `--apply` once scope and summary counts match expectation.
 
-If cleanup changes schema assumptions, follow `docs/ops/migration_checklist.md` before any migration rollout.
+If cleanup changes schema assumptions, follow `docs/operations/migration-checklist.md` before any migration rollout.
 
 ## Restore Drill Cadence
 

docs/operations/overview.md

@@ -0,0 +1,7 @@
+# Operations Documentation
+
+Use this section for production operations and incident/runbook workflows.
+
+- [Scrape Safety Runbook](./scrape-safety-runbook.md)
+- [Database Runbook](./database-runbook.md)
+- [Migration Rollout Checklist](./migration-checklist.md)

docs/reference/overview.md

@@ -0,0 +1,6 @@
+# Reference Documentation
+
+Use this section for canonical contracts and configuration references.
+
+- [API Contract](./api-contract.md)
+- [Environment Reference](./environment.md)

docs/user/getting-started.md

@@ -0,0 +1,41 @@
+# User Getting Started
+
+## Required Setup
+
+1. Copy `.env.example` to `.env`.
+2. Set `POSTGRES_PASSWORD`.
+3. Set `SESSION_SECRET_KEY`.
+
+## Deploy Method A: Prebuilt Image
+
+```bash
+docker compose pull
+docker compose up -d
+```
+
+Open:
+- App/API: `http://localhost:8000`
+- Health endpoint: `http://localhost:8000/healthz`
+
+Upgrade:
+
+```bash
+docker compose pull
+docker compose up -d
+```
+
+## Deploy Method B: Local Source + Dev Frontend
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
+```
+
+Open:
+- API: `http://localhost:8000`
+- Frontend dev server: `http://localhost:5173`
+
+Stop:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.dev.yml down
+```

docs/user/overview.md

@@ -0,0 +1,5 @@
+# User Documentation
+
+Use this section if you are deploying and using scholarr.
+
+- [Getting Started](./getting-started.md)

docs/website/docusaurus.config.js

@@ -0,0 +1,81 @@
+// @ts-check
+
+/** @type {import('@docusaurus/types').Config} */
+const config = {
+  title: "scholarr",
+  tagline: "Self-hosted scholar tracking docs",
+  favicon: "img/favicon.ico",
+
+  url: "https://justinzeus.github.io",
+  baseUrl: "/scholarr/",
+
+  organizationName: "JustinZeus",
+  projectName: "scholarr",
+
+  onBrokenLinks: "throw",
+  onBrokenMarkdownLinks: "warn",
+
+  i18n: {
+    defaultLocale: "en",
+    locales: ["en"],
+  },
+
+  presets: [
+    [
+      "classic",
+      {
+        docs: {
+          path: "..",
+          exclude: ["website/**", "README.md"],
+          routeBasePath: "/",
+          sidebarPath: require.resolve("./sidebars.js"),
+          editUrl: "https://github.com/JustinZeus/scholarr/tree/main/",
+        },
+        blog: false,
+        theme: {
+          customCss: require.resolve("./src/css/custom.css"),
+        },
+      },
+    ],
+  ],
+
+  themeConfig: {
+    navbar: {
+      title: "scholarr",
+      items: [
+        {
+          type: "docSidebar",
+          sidebarId: "docsSidebar",
+          position: "left",
+          label: "Docs",
+        },
+        {
+          href: "https://github.com/JustinZeus/scholarr",
+          label: "GitHub",
+          position: "right",
+        },
+      ],
+    },
+    footer: {
+      style: "dark",
+      links: [
+        {
+          title: "Docs",
+          items: [{ label: "Index", to: "/" }],
+        },
+        {
+          title: "Community",
+          items: [
+            {
+              label: "GitHub",
+              href: "https://github.com/JustinZeus/scholarr",
+            },
+          ],
+        },
+      ],
+      copyright: `Copyright © ${new Date().getFullYear()} scholarr.`,
+    },
+  },
+};
+
+module.exports = config;

docs/website/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "scholarr-docs",
+  "version": "0.0.1",
+  "private": true,
+  "scripts": {
+    "start": "docusaurus start",
+    "build": "docusaurus build",
+    "serve": "docusaurus serve"
+  },
+  "dependencies": {
+    "@docusaurus/core": "3.9.2",
+    "@docusaurus/preset-classic": "3.9.2",
+    "clsx": "^2.1.1",
+    "prism-react-renderer": "^2.3.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  }
+}

docs/website/sidebars.js

@@ -0,0 +1,40 @@
+/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
+const sidebars = {
+  docsSidebar: [
+    "index",
+    {
+      type: "category",
+      label: "Users",
+      items: ["user/overview", "user/getting-started"],
+    },
+    {
+      type: "category",
+      label: "Operations",
+      items: [
+        "operations/overview",
+        "operations/scrape-safety-runbook",
+        "operations/database-runbook",
+        "operations/migration-checklist",
+      ],
+    },
+    {
+      type: "category",
+      label: "Developers",
+      items: [
+        "developer/overview",
+        "developer/documentation-standards",
+        "developer/local-development",
+        "developer/architecture",
+        "developer/contributing",
+        "developer/frontend-theme-inventory",
+      ],
+    },
+    {
+      type: "category",
+      label: "Reference",
+      items: ["reference/overview", "reference/api-contract", "reference/environment"],
+    },
+  ],
+};
+
+module.exports = sidebars;

docs/website/src/css/custom.css

@@ -0,0 +1,9 @@
+:root {
+  --ifm-color-primary: #2a6b4e;
+  --ifm-color-primary-dark: #255f46;
+  --ifm-color-primary-darker: #225942;
+  --ifm-color-primary-darkest: #1c4936;
+  --ifm-color-primary-light: #2f7756;
+  --ifm-color-primary-lighter: #327d5a;
+  --ifm-color-primary-lightest: #3b946b;
+}