# DocWright User Guide

DocWright is a collaborative document-authoring and publishing workspace. You
write in a live editor, every save is a version in your document's own history,
and you can preview the paginated result and take your work away as a portable
bundle at any time. This guide covers the workspace as it exists today (the M2
editor); features still in progress are noted honestly.

---

## 1. Signing in

Go to your DocWright URL (e.g. `https://docwright.jsp.net.in`). If you are not
signed in you are sent to `/login`.

1. Enter your **username** and **password**.
2. If your account has **two-factor authentication (2FA)** enabled, you are
   prompted for your TOTP code (from an authenticator app) on the next step.
3. On success you land on your **workspace dashboard** (`/app`).

Your administrator creates your account and assigns a **role** that governs what
you can do (see [§9](#9-roles--what-you-can-do)). Passwords are hashed with
Argon2id; sign-in is rate-limited.

### Your account & sessions

Visit **`/account`** to manage your session security:

- See your **active sessions / devices** (created, last-seen, IP, user-agent,
  which one is current).
- **Revoke** any individual session.
- **Log out everywhere** — ends all your sessions at once.

Sessions are server-side (stored in PostgreSQL), so they survive a server
restart. They enforce a sliding **idle timeout** and a hard **absolute timeout**;
sensitive actions may require **step-up authentication** (re-auth within a live
session). **Log out** ends the current session (`/logout`).

---

## 2. The workspace / dashboard

The dashboard (`/app`) lists the projects you can access — the ones you own and
those you are a member of (admins see all). Each project shows its title and
document type. From here you can open a project or, if your role permits, create
a new one.

---

## 3. Creating a project from a template

If you have the `projects.create` permission, use **New project** on the
dashboard. Choose a **title**, a **document type**, and a **template**. The
built-in templates are:

| Template | Type | For |
|---|---|---|
| **Boardroom Report** | report | Print-grade board packs and newsletters |
| **Newsletter** | newsletter | Multi-column newsletter with photos |
| **Engineering Report** | report | Technical report with figures and a bill of quantities |
| **Research Paper (LaTeX)** | paper | Academic paper with heavy math and citations |
| **Poster** | poster | Large-format poster |
| **Booklet** | booklet | Saddle-stitch booklet |

Creating a project initialises a **new Git repository** for it (the sovereign
bundle), records the first version, and drops you straight into the editor at
`/editor/<slug>`. Paper-type projects open in *mixed* mode (visual + LaTeX);
others open in *WYSIWYG* mode.

---

## 4. The editor

The editor at `/editor/<slug>` is a live WYSIWYG surface. It renders the
canonical document AST into an editable page, and serialises your edits back to
that AST losslessly (complex nodes — math, citations, figures, tables — are
preserved as locked chips even in the baseline editor). A **save status**
indicator (top) shows `ready`, `unsaved…`, `saving…`, `saved`, or the short
commit hash of your last save. If your role is read-only the editor shows
`read-only` and edits are disabled.

### Toolbar & structure

The toolbar provides inline formatting (**bold**, *italic*, underline, code,
sub/superscript), a **block-type** selector (Body paragraph, Heading 1–3), lists
(bullet / numbered), quote, the **format painter**, **repeat last operation**,
**preview**, and **save version**.

### Command palette (Ctrl/Cmd-K)

Press **Ctrl-K** (Cmd-K on macOS) to open the searchable command palette — every
operation with its current keybinding, VS Code style. Type to filter, use the
arrow keys and **Enter** to run, or click an entry. This keeps power features
discoverable without cluttering the UI. Press **Esc** to close.

### Keyboard shortcuts

`Mod` = **Ctrl** on Windows/Linux, **Cmd** on macOS. (From
`web/js/editor.js` `COMMANDS`.)

| Action | Shortcut |
|---|---|
| Command palette | `Mod-K` |
| Save version | `Mod-S` or `Mod-Shift-S` |
| Bold | `Mod-B` |
| Italic | `Mod-I` |
| Underline | `Mod-U` |
| Heading 1 / 2 / 3 | `Mod-Alt-1` / `Mod-Alt-2` / `Mod-Alt-3` |
| Body paragraph | `Mod-Alt-0` |
| Bullet list | `Mod-Shift-8` |
| Numbered list | `Mod-Shift-7` |
| Quote style | (in palette / toolbar) |
| Format painter | `Mod-Shift-C` |
| Repeat last operation | `Mod-Y` |
| Toggle preview | `Mod-Shift-P` |
| Open history | (in palette / toolbar) |

A configurable keymap (per-user remapping, persisted) is planned — the
`user_preferences` store already exists for it. The palette always shows the
current binding for each command.

### Paragraph styles

Rather than only direct formatting, DocWright uses **named paragraph styles**.
The paragraph-style selector applies a named style (e.g. *Quote*) to the current
paragraph; the document stores the style name on the node so styling is
consistent and reusable. The AST also carries precise paragraph attributes —
alignment, line spacing, space-before/after, first-line and hanging indent,
keep-with-next / keep-together — that render via CSS so preview and print agree.
(The full Styles panel with live "edit a style, update every instance" is
planned; the model and schema for it are in place.)

### Format painter

The **format painter** copies formatting from one place to another:

- **Single use:** click **Format painter** (or `Mod-Shift-C`) to sample the
  formatting at the cursor, then select the target text — the sampled formatting
  is applied once.
- **Sticky / multi-use:** double-click the Format painter button to keep
  painting across multiple selections.

### Repeat last operation

`Mod-Y` re-applies your last discrete editor command (apply a style, insert,
format) to the current selection — handy for repetitive formatting.

---

## 5. Autosave as a Git commit

You do not manage files — DocWright manages **versions**. Every save is a **Git
commit** in your project's own repository:

- **Autosave** — a few seconds after you stop typing, your work is validated
  against the document schema and committed with the message `Autosave`. The
  status line shows the short commit hash.
- **Save version** (`Mod-S`) — you are prompted for a **label**; the commit is
  tagged with an annotated Git tag (`Version: <label>`) so named milestones stand
  out in the history.

If a save fails schema validation, the status line reports it and the commit is
not made — your document on disk always conforms to the schema. If you try to
leave with unsaved changes, the browser warns you.

---

## 6. Revision history & restore

Open **history** (from the toolbar/palette, or `/p/<slug>/history`) to see the
timeline of commits — named versions and autosaves, with author, date, and
message. Because history is real Git, you get the full lineage.

To **restore** an earlier version, choose it in the history view. Restore checks
that revision out and commits it forward as a **new** version (labelled
`Restore <ref>`) — your history is never rewritten, so nothing is lost and you
can always move on again.

---

## 7. Paged preview

Click **Preview** (`Mod-Shift-P`) to open the live paginated preview alongside
the editor. It renders your document through the same CSS Paged Media pipeline
that produces the print PDF, at true page dimensions, so what you see is what the
PDF will print. The editor saves any pending changes first, then refreshes the
preview.

> The in-editor preview renders the document to paginated HTML today. The
> print-exact PDF export (headless Chromium + Paged.js primary; WeasyPrint
> fallback; Tectonic for LaTeX) runs as a queued render job and is part of the
> render-pipeline milestone (in progress).

---

## 8. Exporting the sovereign bundle

At any time you can take your work away. **Export** (`/p/<slug>/export.zip`)
downloads a `.zip` of the entire project bundle at the current version — the
document AST, styles, assets, references, and metadata, all in open,
human-readable formats. Because each project is a plain Git repository, the
bundle is fully portable: you can unzip it, `git clone` it elsewhere, and still
own and read your work without DocWright. This is the sovereignty guarantee — no
feature silently locks your data into the server.

---

## 9. Roles & what you can do

Your global role gates features (deny-by-default). The built-in roles:

| Role | Can |
|---|---|
| **admin** | Everything, including user/session/plugin administration |
| **manager** | Full project & workflow control, approvals, templates, sharing (no server admin) |
| **editor** | Create and edit documents, render/export, comment, share |
| **reviewer** | Read, comment, resolve threads, sign off |
| **viewer** | Read-only |

Access to a specific project is the **intersection** of your project membership
(owner / member) and your global permissions. So even with the `documents.write`
permission you must be a member of a project to edit it, and a share link never
grants more than the recipient's own role allows.

---

## 10. Coming soon

The following are designed into the data model and extension points and are
being delivered as first-party plugins on the core (see
[`ARCHITECTURE.md`](ARCHITECTURE.md)):

- Real-time co-editing with presence (Yjs + a Python CRDT service).
- Threaded comments and **directed RFI threads** (only a named person/group may
  respond/resolve) governed by the workflow engine.
- A configurable **document-control workflow**
  (`Draft → In Review → Approved → Issued`) with role-gated, audited transitions
  and digital sign-off.
- Print-quality **PDF** and faithful **DOCX** export, and one-click **static web**
  publishing.
- **Share links** with QR codes, scopes, and expiry.
- Rich math (MathLive/KaTeX), LaTeX source mode (CodeMirror + Tectonic),
  citations/Zotero, images with hi-res/low-res proxies, smart-art, Indian-language
  transliteration, spell/grammar, and BIM/IFC linking.
- A non-intrusive **feedback & feature-suggestion** tracker.