# Skola Word Plugin

Skola is a Microsoft Word academic writing add-in focused on four core workflows inside Word:

- reference management for citations, figures, tables, abbreviations, and bibliography-related tasks,
- editing and proofing for grammar, clarity, tone, and academic writing quality,
- grounded AI assistance for rewrite, critique, and section drafting,
- source discovery for highlighted claims and citation support.

This repository contains the current working prototype plus the product and architecture documents that describe where the project is heading next.

## Current Prototype Status

The add-in now runs locally in Word with a working pane-first UI. The current implementation includes:

- a Word task pane with `Dashboard`, `Referencing`, `Review`, `Edit`, and `Support Claim` workspaces,
- `Referencing` submenu panels for `Import Citation`, `Delete Selected`, `All Sources`, `New Group`, `Style`, `Figures`, `Tables`, and `Abbreviations`,
- `.ris`, `.xml`, and `.enw` citation import into the local Skola citation library,
- login-gated proofread, critique, rewrite, add-section, and support-claim flows connected to the admin-configured LLM provider,
- user-selectable LLM personalities while provider, model, and API keys remain admin-managed on the API server,
- a classic Office add-in XML manifest with command surface definitions and task pane entry points,
- a webpack-based add-in host with compatibility polyfills for older Word webviews.

Custom ribbon commands remain defined in the manifest, but the pane menu is the primary supported workflow because some older Word clients do not reliably surface custom ribbon tabs.

## Repository Layout

```text
.
|-- apps
|   |-- api
|   `-- word-addin
|-- docs
|   `-- TECHNICAL_ARCHITECTURE.md
|-- packages
|   `-- shared
|-- .env.example
|-- .gitignore
|-- PRD.md
|-- README.md
|-- actionplan.md
|-- package.json
`-- tsconfig.base.json
```

## Workspace Responsibilities

- `apps/word-addin`
  - Office.js task pane and command surface
  - Word selection read/insert flows
  - pane-first workflow navigation and UI rendering
- `apps/api`
  - Fastify API for auth, proofread, AI actions, support-claim LLM prompts, bibliography formatting, and citation-library operations
  - admin-configured OpenAI/Anthropic workflow plus future retrieval and licensed reference-provider integrations
- `packages/shared`
  - shared domain contracts and enums used by both frontend and backend
- `PRD.md`
  - product scope, requirements, and rollout intent
- `docs/TECHNICAL_ARCHITECTURE.md`
  - implementation-oriented architecture and runtime design
- `actionplan.md`
  - delivery checklist showing completed work and remaining milestones

## Local Development

### Prerequisites

- Node.js 20+
- npm 10+
- Microsoft Word desktop with Office add-in sideloading enabled

### Install

```powershell
npm install
```

### Configure MariaDB And Auth Email

Skola now uses MariaDB for accounts, verification tokens, reset tokens, and login sessions.

```powershell
.\scripts\setup-mariadb.cmd
```

The local `.env` and [.env.example](C:\Users\Admin\Documents\OpenAI_Codex\Skola_Word_Plugin\.env.example) default to XAMPP MariaDB on `127.0.0.1:3306` with database `skola`.

Account verification and password reset emails are sent from `RahoshiL@gmail.com` by default. Set `SKOLA_SMTP_PASS` to a Gmail app password for that mailbox before registering users.

### Run the API

```powershell
npm run dev:api
```

### Run the Word add-in host

```powershell
npm run dev:word
```

This serves the add-in over HTTPS on `https://127.0.0.1:3000` using trusted Office dev certificates.

### Sideload into Word

```powershell
npm run sideload:word
```

If Word shows a stale pane or blank cached session, close all Word windows and sideload again from a fresh session.

## Verification Commands

```powershell
npm run typecheck
npm run build
npm run validate:manifest
```

## Runtime Notes

- Local API default: `http://localhost:4000`
- Local add-in host default: `https://localhost:3000` and `https://127.0.0.1:3000`
- The add-in host uses webpack rather than Vite because the older Word webview on this machine did not reliably execute module-based entry scripts.
- The pane is designed to stay useful even when custom ribbon visibility varies by Office version.

## Environment And Integrations

Use [.env.example](C:\Users\Admin\Documents\OpenAI_Codex\Skola_Word_Plugin\.env.example) as the backend integration starting point. The current frontend dev build assumes the local API is available on `http://localhost:4000`.

Admin-controlled LLM settings:

- `SKOLA_LLM_PROVIDER=openai` or `anthropic`
- `SKOLA_LLM_MODEL=<provider model id>`
- `OPENAI_API_KEY=<key>` when using OpenAI
- `ANTHROPIC_API_KEY=<key>` when using Anthropic
- `SKOLA_LLM_TEMPERATURE` and `SKOLA_LLM_MAX_TOKENS` for runtime behavior

Auth and database settings:

- `SKOLA_DB_HOST`, `SKOLA_DB_PORT`, `SKOLA_DB_USER`, `SKOLA_DB_PASSWORD`, and `SKOLA_DB_NAME` configure MariaDB.
- `SKOLA_AUTH_EMAIL`, `SKOLA_AUTH_FROM_EMAIL`, and `SKOLA_AUTH_ADMIN_EMAIL` default to `RahoshiL@gmail.com`.
- `SKOLA_SMTP_HOST`, `SKOLA_SMTP_PORT`, `SKOLA_SMTP_USER`, and `SKOLA_SMTP_PASS` configure outgoing verification and password reset email.

Expected future integration areas include:

- Crossref, OpenAlex, Semantic Scholar, PubMed, and licensed Scopus access for source search,
- reference parsing and formatting infrastructure,
- persistence for user libraries, document sessions, and retrieval indexes,
- institution authentication and policy controls.

## What Is Still Placeholder

- Figure, table, and abbreviation actions are UI-ready but not yet bound to live Word document structures.
- Bibliography regeneration, in-document citation anchors, deduplication, and cross-reference automation are still to be implemented.

## Key Documents

- [PRD.md](C:\Users\Admin\Documents\OpenAI_Codex\Skola_Word_Plugin\PRD.md)
- [TECHNICAL_ARCHITECTURE.md](C:\Users\Admin\Documents\OpenAI_Codex\Skola_Word_Plugin\docs\TECHNICAL_ARCHITECTURE.md)
- [BITBUCKET_EC2_DEPLOYMENT.md](C:\Users\Admin\Documents\OpenAI_Codex\Skola_Word_Plugin\docs\BITBUCKET_EC2_DEPLOYMENT.md)
- [actionplan.md](C:\Users\Admin\Documents\OpenAI_Codex\Skola_Word_Plugin\actionplan.md)

## Notes

- Google Scholar should not be treated as a scraping dependency for MVP.
- Scopus access should be treated as a licensed integration path.
- The current repo is a strong prototype baseline, not yet a production-ready add-in.