# Configuration

> Sync source: `src/core/options.ts`, `src/core/storage/paths.ts`

## Plugin options

Pass in the `plugins` entry of `opencode.json`:

```json
{
  "plugins": [
    {
      "package": "@xirothedev/openoffice-plugin-opencode",
      "options": {
        "pdfEngine": "typst",
        "staleLockHours": 48,
        "dataDir": "/shared/office-plugin-data"
      }
    }
  ]
}
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `pdfEngine` | string | `xelatex` | Pandoc engine for PDF write. Set to `typst` for a lighter engine. |
| `staleLockHours` | number | `24` | Hours before a lock counts as stale and can be force-released. |
| `dataDir` | string | `~/.local/share/opencode/plugins/openoffice/` | Where drafts, locks, history, and sidecars live. |

## Environment variables

- `OFFICECLI_PDF_ENGINE` — overrides `pdfEngine` when the option is not set.

## Data layout

The data dir contains one subdirectory per concern, keyed by SHA-256 of the absolute file path:

```
<dataDir>/
  drafts/     # draft content per (file hash, session)
  locks/      # lock records (sessionID, owner, touchedAt)
  history/    # accept-point snapshots
  registry/   # hash → path index (cross-session discovery)
  sidecars/   # pending metadata, watermarks, annotations
```

The registry maps `filePathHash → absolute path` so other sessions can discover files they have not touched.

## Sidecar data

`metadata`, `watermark`, and `annotate` do not write the real file. They store pending values in a sidecar file under `sidecars/`, keyed by (file hash, session). The values merge into the real file only on `accept`. `undo` or a force-release drops them with the draft.

## Locks

- One lock per file, owned by one session.
- Acquired lazily on the first mutating call (`create`, `edit`, …) — no explicit lock action.
- A foreign lock blocks mutating calls; the error names the owning session.
- After `staleLockHours` of inactivity the lock is stale; `force-release` may take it over. A fresh foreign lock cannot be force-released.
- The displaced session's draft becomes orphaned; its next mutating call fails. Orphaned drafts are logged on plugin shutdown.