Merge pull request #17 from JustinZeus/feat/docs

docs

.github/workflows/ci.yml

@@ -124,10 +124,10 @@ jobs:
           node-version: "20"
 
       - name: Install docs dependencies
-        run: npm install --prefix website
+        run: npm install --prefix docs/website
 
       - name: Docs build
-        run: npm --prefix website run build
+        run: npm --prefix docs/website run build
 
   docker-publish:
     runs-on: ubuntu-latest

.github/workflows/docs-pages.yml

@@ -7,7 +7,6 @@ on:
       - main
     paths:
       - docs/**
-      - website/**
       - .github/workflows/docs-pages.yml
 
 permissions:
@@ -33,15 +32,15 @@ jobs:
           node-version: "20"
 
       - name: Install docs dependencies
-        run: npm install --prefix website
+        run: npm install --prefix docs/website
 
       - name: Build docs site
-        run: npm --prefix website run build
+        run: npm --prefix docs/website run build
 
       - name: Upload pages artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: website/build
+          path: docs/website/build
 
   deploy:
     needs: build

.gitignore

@@ -15,6 +15,6 @@ planning/
 frontend/node_modules/
 frontend/dist/
 frontend/.vite/
-website/node_modules/
-website/build/
+docs/website/node_modules/
+docs/website/build/
 AGENTS.MD

README.md

@@ -4,7 +4,7 @@
 
 Self-hosted scholar tracking with a single app image (API + frontend).
 
-[![CI](https://img.shields.io/github/actions/workflow/status/justinzeus/scholarr/ci.yml?style=for-the-badge)](https://github.com/JustinZeus/scholar-scraper/actions/workflows/ci.yml)
+[![CI](https://img.shields.io/github/actions/workflow/status/justinzeus/scholarr/ci.yml?style=for-the-badge)](https://github.com/JustinZeus/scholarr/actions/workflows/ci.yml)
 [![Docker Pulls](https://img.shields.io/docker/pulls/justinzeus/scholarr?style=for-the-badge&logo=docker)](https://hub.docker.com/r/justinzeus/scholarr)
 [![Docker Image](https://img.shields.io/badge/docker-justinzeus%2Fscholarr-2496ED?style=for-the-badge&logo=docker&logoColor=white)](https://hub.docker.com/r/justinzeus/scholarr)
 
@@ -35,32 +35,11 @@ Open:
 
 ## Documentation
 
-Primary docs live under `docs/`.
+Complete documentation is published at:
 
-- Index: `docs/README.md`
-- Deploy and dev workflow: `docs/deploy/quickstart.md`
-- Environment reference: `docs/reference/environment.md`
-- API contract and payload conventions: `docs/reference/api_contract.md`
-- Architecture and domain boundaries: `docs/architecture/domain_boundaries.md`
-- Scrape safety runbook: `docs/ops/scrape_safety_runbook.md`
-- DB backup/restore/integrity runbook: `docs/ops/db_runbook.md`
-- Migration rollout checklist: `docs/ops/migration_checklist.md`
-- Frontend theme inventory: `docs/frontend/theme_phase0_inventory.md`
-- Contributing policy: `docs/contributing.md`
+- https://justinzeus.github.io/scholarr/
 
-## Docs Site (Docusaurus)
-
-Docusaurus source lives in `website/` and consumes markdown from `docs/`.
-
-Local build:
-
-```bash
-cd website
-npm install
-npm run build
-```
-
-GitHub Pages deploy is automated via `.github/workflows/docs-pages.yml`.
+Source markdown and docs tooling live under `docs/`.
 
 ## Quality Gates
 

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

@@ -7,10 +7,10 @@ const config = {
   favicon: "img/favicon.ico",
 
   url: "https://justinzeus.github.io",
-  baseUrl: "/scholar-scraper/",
+  baseUrl: "/scholarr/",
 
   organizationName: "JustinZeus",
-  projectName: "scholar-scraper",
+  projectName: "scholarr",
 
   onBrokenLinks: "throw",
   onBrokenMarkdownLinks: "warn",
@@ -25,10 +25,11 @@ const config = {
       "classic",
       {
         docs: {
-          path: "../docs",
+          path: "..",
+          exclude: ["website/**", "README.md"],
           routeBasePath: "/",
           sidebarPath: require.resolve("./sidebars.js"),
-          editUrl: "https://github.com/JustinZeus/scholar-scraper/tree/main/",
+          editUrl: "https://github.com/JustinZeus/scholarr/tree/main/",
         },
         blog: false,
         theme: {
@@ -49,7 +50,7 @@ const config = {
           label: "Docs",
         },
         {
-          href: "https://github.com/JustinZeus/scholar-scraper",
+          href: "https://github.com/JustinZeus/scholarr",
           label: "GitHub",
           position: "right",
         },
@@ -67,7 +68,7 @@ const config = {
           items: [
             {
               label: "GitHub",
-              href: "https://github.com/JustinZeus/scholar-scraper",
+              href: "https://github.com/JustinZeus/scholarr",
             },
           ],
         },

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;

website/sidebars.js

@@ -1,6 +0,0 @@
-/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
-const sidebars = {
-  docsSidebar: [{ type: "autogenerated", dirName: "." }],
-};
-
-module.exports = sidebars;