# Backups and restore (/docs/deploying/backups)
Neon's free tier keeps about six hours of history. That covers "I ran the wrong query ten minutes ago", and nothing older. So the hosted version keeps its own backups: every night a GitHub Actions workflow dumps the whole database and stores it in an R2 bucket.
The backup script's upload, retention and download were tested against a stand-in for R2. The dump itself and every restore step on this page were written without being run: there was no `pg_dump` on the machine they were written on. Until someone has done [the rehearsal below](#rehearse-a-restore) once, treat the backups as unproven. When you have, replace this note with the date and what you found.
## What is in a backup [#what-is-in-a-backup]
| | In the nightly dump | Where it lives otherwise |
| ---------------------------------------------- | ------------------- | -------------------------------------------------------------------- |
| Accounts, workspaces, projects, the binder | yes | |
| The current text of every note | yes | also in the collab worker's storage, for notes that have been opened |
| Comments, properties, links, canon, settings | yes | |
| The list of versions and attachments | yes | |
| The bytes of version snapshots and attachments | **no** | the app's R2 bucket (`versions/`, `attachments/`) |
R2 stores objects redundantly, but nothing here keeps a second copy of that bucket. If it were emptied, the text of every note would survive and older versions and attached files would not.
A dump holds everything in the database, including email addresses, password hashes and every manuscript. Keep the bucket private, and delete any copy you download once you are done with it.
## How it runs [#how-it-runs]
* `.github/workflows/backup.yml` runs at 02:23 UTC every night, and whenever you start it by hand (`gh workflow run backup.yml`).
* It runs `scripts/backup.ts`, which calls `pg_dump` (custom format, compressed), uploads the file as `backups/plotra-TZ.dump`, checks the upload's size, and only then deletes old dumps so that the newest 14 remain (`BACKUP_KEEP`).
* If the dump fails or comes out nearly empty, nothing is uploaded and nothing is deleted, and the run fails. A failed scheduled run emails whoever last edited the workflow.
* The secrets and variables it needs are listed in [the deploy checklist](/docs/deploying#7-repository-secrets-and-variables).
Two ways it can stop without anyone touching it: GitHub switches scheduled workflows off after 60 days without a commit to a public repository, and `pg_dump` refuses to dump a database newer than itself, which happens when Neon moves to a new Postgres major version and `PG_MAJOR` hasn't followed. Look at the Actions tab now and then.
## Rehearse a restore [#rehearse-a-restore]
Do this once before anyone's work depends on the hosted version, and again after a Postgres major upgrade. It restores the latest backup into a scratch database next to the real one. It changes nothing in production.
You need the Postgres client tools at the database's major version or newer (`pg_restore --version`), and Bun.
**1. Make a fresh backup and download it.** Use the backup bucket's credentials:
```bash
gh workflow run backup.yml && gh run watch
export S3_ENDPOINT=... # https://.r2.cloudflarestorage.com
export S3_ACCESS_KEY_ID=... # the backup token
export S3_SECRET_ACCESS_KEY=...
export BACKUP_BUCKET=plotra-backups
bun scripts/backup.ts --list
bun scripts/backup.ts --download # the newest, into the current directory
```
**2. Check the file is a readable dump.**
```bash
pg_restore --list plotra-*.dump | head -40
```
It prints a table of contents: tables, indexes, policies. If it prints an error instead, the backup is bad. Stop here and find out why before anything else.
**3. Create an empty database beside the real one.** In the Neon console: **Databases → New database**, named `restore_test`, in the same project and branch. A database in the same project already has the `plotra_app` role the dump refers to. Copy its **direct** connection string.
```bash
export RESTORE_URL=""
```
**4. Restore.**
```bash
pg_restore --no-owner --dbname="$RESTORE_URL" plotra-*.dump
```
It should finish without printing anything. If it ends with "errors ignored on restore", read each error above that line: an error about a role or a permission means the restored database would not work with the app, and this page needs correcting.
**5. Compare with production.** Run this against both databases (`psql "$RESTORE_URL"` and `psql ""`). The restored numbers should equal production's as of the backup:
```sql
select
(select count(*) from "user") as users,
(select count(*) from project) as projects,
(select count(*) from node) as notes,
(select coalesce(sum(word_count), 0) from node) as words,
(select count(*) from pg_policies) as policies,
has_table_privilege('plotra_app', 'node', 'select') as app_role_can_read;
```
`policies` must be more than zero and `app_role_can_read` must be `t`. Those two are the row-level security the app runs under; a restore that loses them produces an app where nobody can see their own work.
**6. Open it in the app.** Numbers can match while the app still can't read the data. Run the app locally against the restored database:
```bash
cd apps/app
DATABASE_URL="$RESTORE_URL" bun run dev
```
Start it from `apps/app` as shown, not with `bun dev:app` from the root: Turborepo doesn't pass `DATABASE_URL` through, and the app would quietly open your development database instead. To open a note in the editor, run the collab worker too (`bun run dev` in `apps/collab`, in a second terminal).
Sign in with your production email and password and open a project you know. You should see the production projects, not your development ones, and your notes with their text. (An account that only ever signed in with Google has no password; use one that has. Version history and attachments open only if your local `.env.local` points at the production bucket, which this test doesn't need.)
**7. Clean up.** Delete the `restore_test` database in the Neon console, delete the downloaded dump, and unset the variables. Then replace the warning at the top of this page with the date and anything that differed from what is written here.
## When the database is lost or damaged [#when-the-database-is-lost-or-damaged]
First decide which restore you need.
* **Something went wrong in the last few hours** (a bad migration, a wrong `delete`): use Neon's own point-in-time restore from its console. It is faster and loses less than a nightly dump.
* **The damage is older than Neon's history, or the Neon project is gone:** restore the nightly dump, as follows.
Anything written after the dump was taken is not in it. The collab worker narrows that gap for text, as step 5 explains.
**1. Download the dump you want.** `bun scripts/backup.ts --list`, then `bun scripts/backup.ts --download `, with the variables from the rehearsal. Pick the newest dump from before the damage.
**2. Create the database to restore into.** Never restore over the damaged one: you may still need it.
* A new database in the same Neon project already has the role the dump needs.
* In a **new** Neon project, create that role first, as the project's owner:
```sql
CREATE ROLE plotra_app NOLOGIN NOBYPASSRLS;
GRANT plotra_app TO CURRENT_USER;
```
**3. Restore, then bring the schema up to date.**
```bash
pg_restore --no-owner --dbname="$RESTORE_URL" plotra-.dump
DATABASE_URL="$RESTORE_URL" bun run db:migrate
```
The dump carries the list of migrations it was taken at, so `db:migrate` applies only the ones added since. Run the comparison query from the rehearsal and check `policies` and `app_role_can_read`.
**4. Point the app at it.** In the Vercel project for `apps/app`, set `DATABASE_URL` to the new database's **pooled** connection string and redeploy. Set the `BACKUP_DATABASE_URL` repository secret to its **direct** string, or tonight's backup dumps the old database.
**5. Know what the collab worker does next.** The worker keeps its own copy of every document that has been opened, and that copy is as new as the last keystroke. When someone opens a note after the restore, the worker's copy is what they see, and it is written back to the database. So for notes that exist in the restored database, text typed after the backup comes back by itself.
What does not come back: notes created after the backup (the restored database has no row for them, so the worker has nowhere to write), and everything that isn't document text, such as the binder's structure, comments, properties and sharing.
The same behaviour means a restore can't be used to roll a document's text back: the worker's newer copy wins. For one document, use its version history instead.
**6. Expect two loose ends.** People are signed out if their session was created after the backup. And a version or attachment that was deleted after the backup is listed again but its file is gone from R2; opening it says the snapshot is missing.
**7. Tell people.** Say what was lost and from when. Then write down what happened and fix this page where it was wrong.
# Deploying the hosted version (/docs/deploying)
This is the order to do things in the first time the hosted version goes up. Each step ends with a check; don't start the next one until it passes. To run Plotra on your own server instead, see [Self-hosting](/docs/self-hosting).
Everything here except [Plans and billing](#plans-and-billing-creem) fits in a free tier. What each one allows, and what it would cost past that, is in [the README](https://github.com/ItzSudhan/plotra#what-it-costs-to-run).
Vercel's Hobby plan is for non-commercial use. Once the Pro checkout is live, the app has to be on Vercel Pro (about $20 a month) or on another host. Do [Plans and billing](#plans-and-billing-creem) only after that move. Until `CREEM_API_KEY` is set there are no plans, nothing is sold, and Hobby is allowed.
## Addresses [#addresses]
The page is written for one domain, {domain}. To use another, change `domain` at the top of this file and the `DOMAIN` line below.
| What | Address | Runs on |
| ----------------------------- | --------------------------------------------------- | ------------------ |
| Marketing site (`apps/web`) | {site} | Vercel |
| App (`apps/app`) | {app} | Vercel |
| Docs (`apps/docs`) | {docs} | Vercel |
| Collab worker (`apps/collab`) | {collab}, or its `workers.dev` address | Cloudflare Workers |
The commands on this page use these shell variables. Set them once in the terminal you work in:
```bash
DOMAIN=plotra.ink
APP_URL=https://app.$DOMAIN
```
Generate two secrets now and keep them in a password manager. You will paste each in two places.
```bash
openssl rand -base64 32 # BETTER_AUTH_SECRET: signs sessions
openssl rand -base64 32 # COLLAB_SECRET: shared by the app and the collab worker
```
## 1. Database: Neon [#1-database-neon]
1. Create a Neon project. Choose **Postgres 18** and the region closest to where Vercel runs the app's functions (`iad1`, Washington D.C., unless you change it).
2. From **Connect**, copy two connection strings:
* the **pooled** one (its host contains `-pooler`): the app's `DATABASE_URL`;
* the **direct** one (pooling switched off): for migrations and for backups.
3. Run the migrations from the repository root, against the direct string:
```bash
bun install
DATABASE_URL="" bun run db:migrate
```
A `DATABASE_URL` in the environment wins over `apps/app/.env.local`, so this does not touch your development database.
**Check:** in Neon's SQL editor, `select count(*) from pg_policies;` returns more than zero, and `select rolname from pg_roles where rolname = 'plotra_app';` returns one row. The migrations create that role; the app's row-level security depends on it.
## 2. Files: Cloudflare R2 [#2-files-cloudflare-r2]
Version snapshots and attachments must go to R2 in production. Without it they are stored in Postgres, and Neon's free storage would be gone within weeks.
1. In the Cloudflare dashboard, open **R2** and create two buckets: `plotra` for the app and `plotra-backups` for database dumps. Leave both private: no public access, no `r2.dev` address.
2. Create two API tokens under **R2 → Manage API tokens**, each with **Object Read & Write** and limited to one bucket:
* one for `plotra`, used by the app;
* one for `plotra-backups`, used by the backup workflow. Kept apart, a leaked app credential can't delete the backups.
3. Note each token's access key ID and secret access key, and your Cloudflare **account ID**.
**Check:** both buckets are listed and empty.
## 3. The three Vercel projects [#3-the-three-vercel-projects]
Vercel's Hobby plan can't be connected to a repository owned by a GitHub organization. The repository has to be under a personal account. (On Vercel Pro, which paid plans need, that restriction goes away.)
For each of `apps/app`, `apps/web` and `apps/docs`:
1. **Add New… → Project**, import the repository, and set **Root Directory** to the app's folder. Leave "Include files outside the root directory" on: the shared packages live outside it.
2. Leave the build settings alone. Each app has a `vercel.json` that sets the framework and the build command, and Vercel installs with Bun because the repository has a `bun.lock`.
3. Add the environment variables below (Production environment), then deploy.
4. Under **Settings → Domains**, add the app's address from the table above and create the DNS record Vercel asks for.
Vercel skips a project's build when a commit changes nothing it depends on. That is on by default for new projects (**Settings → Build and Deployment → Root Directory → Skip deployment**) and works with Bun workspaces, so a docs change doesn't rebuild the app.
### `apps/app` [#appsapp]
| Variable | Value |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `DATABASE_URL` | Neon's **pooled** connection string |
| `BETTER_AUTH_SECRET` | the first secret you generated |
| `BETTER_AUTH_URL` | {app}, without a trailing slash |
| `COLLAB_SECRET` | the second secret you generated |
| `NEXT_PUBLIC_COLLAB_URL` | the collab worker's address. Set it in step 4, when you know it. |
| `S3_ENDPOINT` | `https://.r2.cloudflarestorage.com`, with the Cloudflare account ID from step 2 |
| `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` | the **app** token from step 2 |
| `S3_BUCKET` | `plotra` |
| `NEXT_PUBLIC_SITE_URL` | {site} |
| `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` | from step 5 |
| `SMTP_URL`, `EMAIL_FROM` | from step 6 |
| `SENTRY_DSN` | optional, see [Error tracking](#error-tracking) |
| `AI_KEY_SECRET` | optional: `openssl rand -base64 32`. Lets people save their own AI provider key; without it that feature is off. |
| `CREEM_…`, `AI_…` | optional, see [Plans and billing](#plans-and-billing-creem). Without `CREEM_API_KEY` there are no plans at all. |
A Vercel Function can't receive a request body larger than 4.5 MB, and uploads go through one. Vercel would reject a larger file with an error page before the app sees it, so on Vercel the app limits files to 4 MB itself and says "Files can be up to 4 MB" instead. Larger files need uploads that go straight to R2, which is not built yet. Until then the file sizes the plans name (10 MB on Free, 100 MB on Pro) can't be reached on Vercel.
### `apps/web` [#appsweb]
| Variable | Value |
| ---------------------- | ------------------- |
| `NEXT_PUBLIC_APP_URL` | {app} |
| `NEXT_PUBLIC_DOCS_URL` | {docs} |
| `NEXT_PUBLIC_SITE_URL` | {site} |
### `apps/docs` [#appsdocs]
| Variable | Value |
| ---------------------- | ------------------- |
| `NEXT_PUBLIC_DOCS_URL` | {docs} |
| `NEXT_PUBLIC_APP_URL` | {app} |
| `NEXT_PUBLIC_SITE_URL` | {site} |
Variables that start with `NEXT_PUBLIC_`, and `SENTRY_DSN`, are read when the project is built. After changing one, redeploy.
**Check:**
```bash
curl -s $APP_URL/api/health
```
answers with `"ok":true`, `"database":"ok"`, `"objectStore":true` and an empty `warnings` list. `collab`, `email` and `googleSignIn` turn true as the next steps are done. The health endpoint only ever says whether a service is configured, never a value.
```bash
curl -sI $APP_URL/sign-in | grep -i -E "strict-transport|x-frame|x-content-type|referrer-policy"
```
prints four headers.
## 4. Collab worker: Cloudflare Workers [#4-collab-worker-cloudflare-workers]
The worker's production settings are the `production` environment in `apps/collab/wrangler.jsonc`.
1. If your app address is not {app}, change `APP_URL` under `env.production.vars` in `apps/collab/wrangler.jsonc`. It must equal the app's `BETTER_AUTH_URL` exactly: the worker checks every token against it.
2. Deploy, then give the worker its secret (the same `COLLAB_SECRET` as the app):
```bash
cd apps/collab
bunx wrangler login
bun run deploy # wrangler deploy --env production
bunx wrangler secret put COLLAB_SECRET --env production
```
Always deploy with `bun run deploy`. A plain `wrangler deploy` ships the local settings, and the worker's health check then answers 503.
3. The deploy prints the worker's address, `https://plotra-collab..workers.dev`. That address works as it is. To use {collab} instead, the domain's DNS zone has to be on Cloudflare: uncomment the `routes` line in `wrangler.jsonc` and deploy again.
4. In the Vercel project for `apps/app`, set `NEXT_PUBLIC_COLLAB_URL` to the worker's address (with `https://`) and redeploy the app.
**Check:**
```bash
curl -s https:///health # {"ok":true}
```
and `/api/health` on the app now shows `"collab":true`.
## 5. Google sign-in [#5-google-sign-in]
In the Google Cloud console, under **Google Auth Platform**:
1. **Branding:** app name, support email, the app's home page ({site}), a privacy policy link ({site}/privacy) and terms link ({site}/terms), and the authorized domain (the registrable domain, `itzsudhan.com`).
2. **Audience:** External, and **publish the app** so it is "In production". While it is in testing, only listed test users can sign in. Plotra asks only for name, email and profile picture, which need no sensitive-scope review; Google may still ask to verify the branding before it shows the app's name and logo.
3. **Clients → Create client → Web application:**
* Authorized JavaScript origin: {app}
* Authorized redirect URI: {app}/api/auth/callback/google
Keep a separate client for `http://localhost:3000` rather than adding localhost to this one.
4. Put the client ID and secret in the app's Vercel project as `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`, and redeploy.
**Check:** the sign-in page shows "Continue with Google", and signing in with a Google account that is not yours works.
## 6. Email: SMTP [#6-email-smtp]
Plotra sends email over SMTP, so any mail service works. These steps use Resend.
1. In Resend, **Domains → Add domain**. A subdomain kept for sending, such as `mail.plotra.ink`, keeps the app's mail reputation apart from everything else on the domain.
2. Add the DNS records Resend lists: the **SPF** record (a TXT and an MX on the `send` subdomain) and the **DKIM** record (a TXT at `resend._domainkey`). Add a DMARC record too if the domain has none: a TXT at `_dmarc` with `v=DMARC1; p=none;`.
3. Wait for Resend to show the domain as verified, then create an API key with **Sending access** limited to that domain. It is the SMTP password.
4. In the app's Vercel project set `SMTP_URL` to `smtps://resend:@smtp.resend.com:465`, and `EMAIL_FROM` to an address on the verified domain, for example `Plotra `. Redeploy.
Resend's free tier sends 3,000 emails a month and 100 a day. The app limits invitations and shares per person to stay well inside that.
**Check:** invite an address at another mail provider to a workspace. The mail arrives in the inbox, not in spam, and its headers ("Show original" in Gmail) say `SPF: PASS` and `DKIM: PASS`.
## 7. Repository secrets and variables [#7-repository-secrets-and-variables]
The repository has three workflows. `ci.yml` needs nothing. The other two do nothing until these exist, under **Settings → Secrets and variables → Actions**.
| Kind | Name | Value | Used by |
| -------- | ----------------------------- | ------------------------------------------------------------ | ------------ |
| Variable | `APP_URL` | {app} | `uptime.yml` |
| Variable | `COLLAB_URL` | the worker's address, with `https://` | `uptime.yml` |
| Variable | `BACKUP_BUCKET` | `plotra-backups` | `backup.yml` |
| Variable | `BACKUP_KEEP` | optional: how many dumps to keep. Default 14. | `backup.yml` |
| Variable | `PG_MAJOR` | optional: the database's Postgres major version. Default 18. | `backup.yml` |
| Secret | `BACKUP_DATABASE_URL` | Neon's **direct** connection string | `backup.yml` |
| Secret | `S3_ENDPOINT` | `https://.r2.cloudflarestorage.com` | `backup.yml` |
| Secret | `BACKUP_S3_ACCESS_KEY_ID` | the **backup** token's access key ID | `backup.yml` |
| Secret | `BACKUP_S3_SECRET_ACCESS_KEY` | the **backup** token's secret access key | `backup.yml` |
With the GitHub CLI:
```bash
gh variable set APP_URL --body "$APP_URL"
gh variable set COLLAB_URL --body "https://"
gh variable set BACKUP_BUCKET --body "plotra-backups"
gh secret set BACKUP_DATABASE_URL # paste when asked
gh secret set S3_ENDPOINT
gh secret set BACKUP_S3_ACCESS_KEY_ID
gh secret set BACKUP_S3_SECRET_ACCESS_KEY
```
The uptime check runs every half hour, about 1,500 runner minutes a month. That is free in a public repository. A private one gets 2,000 minutes a month for everything, so leave `APP_URL` and `COLLAB_URL` unset until the repository is public.
A failed scheduled run emails the person who last edited the workflow file. Make sure GitHub may send it: **your profile → Settings → Notifications → Actions**, with email on for failed workflows.
**Check:** `gh workflow run uptime.yml`, then `gh run watch`. The run is green.
## 8. First backup, and a restore [#8-first-backup-and-a-restore]
```bash
gh workflow run backup.yml
gh run watch
```
**Check:** the run is green and `plotra-backups` holds one object under `backups/`.
Then restore it. A backup that has never been restored is a guess. The steps are in [Backups and restore](/docs/deploying/backups#rehearse-a-restore), and they take about fifteen minutes. Do it before inviting anyone.
## Plans and billing: Creem [#plans-and-billing-creem]
Optional, and the last thing to switch on. Without `CREEM_API_KEY` the app has no plans: no Free or Pro, no checkout, no Plan & billing tab. What the plans are is in [Plans and billing](/docs/guide/plans).
Before you start, move the app's Vercel project to Vercel Pro, or to another host. See the note at the top of this page.
1. Run the migration that adds the billing tables, if the database was created before it existed: `DATABASE_URL="" bun run db:migrate`.
2. In [Creem](https://creem.io), switch to **test mode** and create two subscription products: Pro monthly at $10, and Pro yearly at $96. Note each product's id.
3. Create a test API key. It starts with `creem_test_`, and the app then talks to Creem's test API.
4. Register a webhook at {app}/api/billing/webhook and copy its signing secret.
5. Set these on the app's Vercel project and redeploy:
| Variable | Value |
| --------------------------- | --------------------------------------------------------------------- |
| `CREEM_API_KEY` | the API key. One that starts with `creem_test_` uses Creem's test API |
| `CREEM_WEBHOOK_SECRET` | the webhook's signing secret |
| `CREEM_PRODUCT_PRO_MONTHLY` | the Creem product id of the monthly product |
| `CREEM_PRODUCT_PRO_YEARLY` | the Creem product id of the yearly product |
For hosted AI, the model Pro workspaces use with their credits, also set:
| Variable | Value |
| --------------------------------- | ----------------------------------------------------------------------------- |
| `AI_PROVIDER` | the provider: `anthropic`, `openai`, `openrouter` or `compatible` |
| `AI_API_KEY` | the project's own key at that provider. These calls are on the project's bill |
| `AI_BASE_URL` | only for a provider that needs a URL |
| `AI_MODEL_AGENT`, `AI_MODEL_FAST` | the model for agent runs, and the cheaper one for inline actions |
All of these are optional. Without the `AI_` values, Pro has no hosted AI and the agent runs on people's own keys only.
**Check, in test mode:** open a workspace's settings at `/w//settings?tab=billing`, upgrade with one of Creem's test cards, and see the workspace on Pro when you come back. Cancel it, and see that it says Pro runs until the end of the period. In Creem's dashboard the webhook deliveries show as successful.
6. When that works, repeat steps 2 to 5 in Creem's live mode: live products, a live API key, a live webhook and its secret. Name the hosted AI provider on the site's privacy page before the first person pays.
## Error tracking [#error-tracking]
Optional. Create a project in Sentry (the free plan is enough), copy its DSN, set `SENTRY_DSN` on the app's Vercel project and redeploy. Server errors and browser errors then arrive with a stack trace and the route they happened on. Request bodies, cookies and query strings are never sent, so no one's writing leaves the app in an error report. Without `SENTRY_DSN` nothing is sent and the browser loads no reporting code.
**Check:** open the app, open the browser console and run:
```js
setTimeout(() => { throw new Error("Sentry test from the console") });
```
The error appears in Sentry within a minute.
## 9. Smoke test, in two browsers [#9-smoke-test-in-two-browsers]
Use two different browsers (or one normal window and one private window), with two accounts: **A** and **B**. Every line should work. If one doesn't, stop and fix it before the next.
1. **A** signs up with email and password. **B** signs in with Google.
2. **A** creates a project, opens a scene and writes a paragraph. Reload the page: the paragraph is still there.
3. **A** shares the project with **B**'s email as an editor. The email arrives; **B** opens the link and sees the project.
4. Both open the same scene. Each sees the other's cursor. Both type at once, in different paragraphs and then in the same one: both screens end up with the same text.
5. **B** turns off the network, types a sentence, and turns it back on. The sentence reaches **A**.
6. **A** saves a named version, changes the text, and restores the version. In the Cloudflare dashboard the `plotra` bucket now has an object under `versions/`.
7. **A** creates a research note and attaches an image under 4 MB. **B** can open it. The bucket has an object under `attachments/`.
8. **B** comments on a passage; **A** replies and resolves it.
9. **A** changes **B** to a viewer. **B** can still read and can no longer type.
10. **A** exports the project and opens the file.
11. **A** switches on the read-only link in the Share dialog and opens it in a window that is not signed in.
12. `curl -s $APP_URL/api/health` shows every service `true` and no warnings.
13. In the Vercel project's logs for the last hour there is no line starting with `[plotra] WARNING`.
When all of it passes, add the uptime variables if you held them back in step 7, and the hosted version is up.
## After the first deploy [#after-the-first-deploy]
* **App, site, docs:** pushing to `master` deploys them. Nothing to run.
* **Collab worker:** `bun run deploy` in `apps/collab` when `apps/collab` changes. It is not deployed automatically.
* **Database migrations:** when a release adds one, run `DATABASE_URL="" bun run db:migrate` before the push that needs it reaches `master`.
* **Postgres upgrade:** when the database moves to a new major version, set the `PG_MAJOR` variable to match, or the nightly backup fails.
# The AI agent (/docs/guide/ai)
Plotra works without AI. The agent is off until someone turns it on, and with it off no AI control is shown anywhere.
When it is on, it works inside a project like a collaborator: it can answer questions about the story, draft and rewrite, and change the binder, properties, timeline and the rest. It does all of that as **you**: it can open and change only what you can.
## Turning it on [#turning-it-on]
Two switches, both off by default:
1. **The workspace:** an owner or admin opens Workspace settings and turns on AI.
2. **The project:** in Project settings, turn on the **AI** module.
Only people who can edit the project can run the agent. Viewers and commenters never see it.
## Whose model it runs on [#whose-model-it-runs-on]
The agent needs a model. There are four ways to give it one.
| | Who pays | Where the text goes |
| ---------------------------------------------------- | ------------------------------- | ------------------------ |
| **Your own key** | You, on your provider's bill | The provider you chose |
| **A local model** | Nobody | Your own machine |
| **Hosted AI** (Pro workspaces on the hosted version) | The workspace's monthly credits | The provider Plotra uses |
| **The instance's key** (self-hosted) | Whoever runs the server | The provider they chose |
### Your own key [#your-own-key]
Open your account menu, choose **Your settings**, then **AI**. Pick a provider (Anthropic, OpenAI, OpenRouter, or any OpenAI-compatible endpoint), paste a key, and name two models: one for agent runs, and a cheaper, faster one for the inline actions in the editor. **Test** makes one tiny call on each and tells you what the provider said.
The key is yours alone. It is stored encrypted, used only for your own runs, never shown again and never shared with collaborators. A collaborator who runs the agent uses their own key.
### A local model [#a-local-model]
Choose **Ollama (local model)**, or an OpenAI-compatible endpoint with a local address such as LM Studio's. The agent needs a model that supports tool calling; a model without it can still do the inline actions.
* **On a self-hosted Plotra** the server calls the model. Whoever runs the server sets `AI_ALLOW_PRIVATE_URLS=true` so that addresses on the local network are allowed.
* **On the hosted version** the server can't reach your computer, so **your browser calls the model directly**. What the model is sent and what it writes go between your browser and that model, and to no provider. A key for the endpoint, if it needs one, is kept in your browser and never sent to Plotra. The server still builds the instructions, runs the agent's tools as you, and stores the conversation, as for any run.
Two things have to be set on the model server, or it won't work:
* **Allow the app's address.** A model server refuses requests from web pages it doesn't know. With Ollama, set `OLLAMA_ORIGINS` to the app's address, for example `OLLAMA_ORIGINS=https://app.plotra.com ollama serve`.
* **Give it a larger context.** Ollama's default context is 4,096 tokens and it cuts off what doesn't fit without saying so. The agent's instructions and tools alone are larger than that, so on the default the model behaves as if it had no tools. Set `OLLAMA_CONTEXT_LENGTH=16384` or more. This applies to a self-hosted Plotra calling Ollama as well.
Limits of a browser-called model: long jobs are not available (they need a model the server can reach), the model has to be at `localhost` or behind https (a secure page can't call plain http on your network), closing the tab mid-run loses the answer being written (what it already changed can still be undone), and after switching to a local model an open project needs a reload.
### Hosted AI [#hosted-ai]
On the hosted version, a workspace on Pro has 1,500 credits a month and nobody needs a key. One credit is 1,000 input tokens; output tokens count five times. Credits reset with the billing period and don't roll over. If you have your own key, your runs use it and spend no credits. See [Plans](/docs/guide/plans).
## Where to find it [#where-to-find-it]
* **The AI tab** in the right sidebar, or **AI** as a view in any pane: a chat, with every step the agent takes listed as it happens. Type `@` to point it at a note. Answers link to the notes they drew on.
* **In the editor:** select some text, or put the caret on an empty line, and press `⌘J` (also in the floating toolbar and the `/` menu): continue, rewrite, shorten, expand, change tone. The answer can replace the text or arrive as a suggestion.
* **The command palette (`⌘P`):** "Ask AI…", "AI: Draft this scene or chapter", "AI: Check this chapter", "AI: Carry a change through the project…", "AI: Build the project from a premise…". Each puts a request in the chat box for you to finish and send.
## The three modes [#the-three-modes]
| Mode | What it may do |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ask** | Reads what you can read. Changes nothing. |
| **Suggest** | Edits to a note's text arrive as suggestions (tracked changes) for you to accept or reject in the Comments tab, shown as "AI, for your name". Anything else, such as moving notes or changing properties, asks you first. |
| **Auto** | Changes apply straight away. It still asks before moving anything to the trash, before changing canon status, and once when a run goes past five notes. |
When the agent asks, the run stops and shows **Allow**, **Don't** and **Allow all**. Sending another message without answering counts as "no".
Some things the agent can never do, in any mode: change who a project is shared with or who is in the workspace, change workspace settings, read or change API keys, delete anything permanently or empty the trash, or publish the public wiki.
## Undoing a run [#undoing-a-run]
* The first time a run changes a note's text, that note is saved as a version named "Before AI". These versions count against the workspace's storage; if storage is full, the edit is refused rather than made without a way back.
* **Undo run**, under an answer, takes back everything that run changed: text, properties, moves, new notes.
* When a run ends, each note it wrote gets a version named "AI, for your name", so the history shows what was the agent's.
Replacing a block replaces the whole block. If someone is typing in that same paragraph at that moment, their keystrokes there are lost.
## The story brief [#the-story-brief]
A top-level note called **Story brief** is sent with every run: genre, voice, tense, point of view, the rules of the world, things to avoid. A project without one shows "Add a story brief" in the AI panel, which makes one from a template. It is the most useful thing you can write for the agent; without it the agent guesses the voice from whatever it happens to read.
## What it knows about your story [#what-it-knows-about-your-story]
The agent doesn't load the whole project. It looks things up: the binder outline, project search, a note's text, entities and their properties, backlinks, the timeline, relationships, who knows what, open setups, and the continuity checks.
It is told to respect [canon](/docs/guide/canon): canon status, the spoiler horizon when you ask for something "as of" a release, and what the point-of-view character knows at that point in the story. After writing, it is told to run the continuity checks on what it touched. These are instructions to a model, not guarantees: a weak model ignores them more often.
## Long jobs [#long-jobs]
Drafting an act is too long for one request. Ask for it and the agent saves a list of steps instead. Press **Start**, and the steps run one at a time; a dropped connection picks up at the next step. Starting the job is your approval of its list, so steps create and change notes without asking, but nothing is moved to the trash and canon is not changed inside a job. **Undo all** takes back every step.
## What is sent, and where [#what-is-sent-and-where]
* Nothing leaves Plotra until someone runs the agent or an inline action.
* A run sends the model what it needs for the task: your request, the story brief, and the notes the agent reads along the way. It goes to the provider for that run and nowhere else: the provider of the key of **the person who ran it**, the provider Plotra uses on a hosted run, or nowhere at all with a local model.
* A collaborator who can edit your project can run the agent on it, and the notes it reads then go to their provider. If you don't want that, leave AI off for the project.
* What a provider does with the text is between the key's owner and that provider. Read their terms on retention and training.
* Plotra never trains a model on your work. It doesn't have one.
* Plotra keeps the conversation (your messages, the agent's answers and its steps) so the thread is there when you come back, and a row per run with the model's name and the number of tokens. Each answer shows its tokens, so you can see what it cost you.
## Text the agent doesn't trust [#text-the-agent-doesnt-trust]
Clipped web pages, imported files, comments from guests and notes from a shared world can contain text written to look like instructions ("ignore your instructions and…"). The agent is given such text inside a marked block and told that it is material to read, never orders to follow. This lowers the risk; it does not remove it. Ask mode can't change anything, and in the other modes trashing and canon changes always stop to ask you.
## Which models [#which-models]
What has actually been tested is listed here, and nothing else is claimed. See `apps/app/evals/README.md` in the repository for the evaluation set and how to run it against a model of your own.
# Canon and the spoiler horizon (/docs/guide/canon)
This is the part of Plotra that other writing tools don't have. It answers three questions that get harder with every book: what is actually true in this world, what has the audience been told so far, and who in the story knows it. With those answered in the project, a series stays consistent without you rereading it, and a contradiction is found by you, not by a reader.
These tools belong to two modules.
| Module | What it adds |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **World bible** | Entity types of your own, canon status and retcon history, the **Continuity** view with its checks and character sheets. |
| **Releases & reveals** | Releases, reveals and channels, the spoiler horizon, the **Release roadmap** and **Secrets & setups** views. |
A tabletop RPG project starts with both on. A franchise project starts with **World bible**. Every other type starts with neither: turn them on in the **Modules** tab of [Project settings](/docs/guide/project-settings), which needs someone who manages the project. Turning a module off hides its tools and keeps everything you recorded. See [Modules](/docs/modules).
Everyone who can open the project can read all of this. Changing it needs edit access: viewers and commenters see the same views with the controls switched off.
## The world bible [#the-world-bible]
Characters and locations are built in. For everything else, define your own **entity types**: a faction, an object, a species, a magic system, a legal case. Each type has its own name, icon, colour and fields.
Every page of a type is an ordinary note, a **World entry**. It has a body, tags, a synopsis and a canon status, it can be linked with `[[`, it has backlinks, and it appears in the graph. Its fields show in the **Properties** panel. The **Codex** view (`⌘⇧C`) lists the pages by type; see [World views](/docs/guide/world-views).
### The types you start with [#the-types-you-start-with]
The first time the project is opened with **World bible** on, it gets nine types. Rename, reshape or delete any of them.
| Type | Fields |
| -------- | ------------------------------------------------------------------------------------------------------------ |
| Faction | Kind (Nation, Organisation, Guild, Family, Cult, Company), Leader (a character), Based in (a location), Goal |
| Object | Owner (a character), Kept at (a location), Significance |
| Event | Story date, Location (a location), Participants (several characters) |
| Species | Habitat, Lifespan, Sapient (a checkbox) |
| Culture | Homeland (a location), Values |
| Language | Family, Script |
| Religion | Deities, Tenets |
| System | Source, Limits & costs |
| Theme | Statement |
With the **Interactive narrative** module on, a **Quest** type is added too. See [Interactive narrative](/docs/modules/interactive).
A project with no types at all gets the nine again the next time it is opened. Keep at least one type if you don't want them back.
### Creating and editing a type [#creating-and-editing-a-type]
Open the type dialog from either place:
* the **Codex** view: **New type…** at the bottom of the list of types, or the pencil beside a type (**Edit type and fields**);
* **Project settings**, the **Kinds** tab: **New kind…**, or **Edit** beside a kind.
| Field | What it does |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | What one page is called: "Faction". Required, up to 80 characters. It is the name used in the binder's **New…** menu and in **Change kind**. |
| **Plural** | The heading of its section in the Codex. Left empty, it is the name with an "s". |
| **Icon** | One of 24 icons. |
| **Colour** | The colour of the icon in the binder, the Codex and the graph. |
| **Fields** | The properties every page of this type has. |
Each field has a name (up to 60 characters) and a type:
| Field type | Holds |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Text | A line of text. |
| Number | A number. |
| Date | A date. |
| Select | One choice from a list. Type the **Choices, separated by commas**. |
| Multi-select | Several choices from a list. |
| Link to note | Another note. Under **Links to**, tick the kinds it may point at (none ticked means any note). Tick **Several** to let it hold more than one. |
| Checkbox | Yes or no. |
| URL | A web address. |
Use the arrows to reorder fields and the bin to remove one. **Add a field** adds a row. A field with no name is dropped when you save.
Things to know about fields:
* A field's type can't be changed once the type has been saved. Remove the field and add a new one.
* Removing a field hides its values; it doesn't erase them. Add a field with the same name again and they come back.
* A field that links to a note counts as a link: the page it points at lists this one under [Backlinks](/docs/guide/links#backlinks).
* Limits: 40 fields per type, 100 choices per list, 60 types per project.
**Delete type** removes the type after a confirmation. Its pages stay in the binder as plain notes, with their text untouched.
### Creating a page [#creating-a-page]
With **World bible** on, each type has an entry in the binder's **New…** menu. In the Codex, select the type and press the plus beside the search box. To turn an existing note into a page of a type, right-click it and choose **Change kind**. See [The vault and the binder](/docs/guide/vault-and-binder#changing-a-notes-kind).
## Canon status [#canon-status]
Every note has a canon status. A new note is **Draft**.
| Status | Meaning |
| ----------- | ------------------------------------------------- |
| Canon | Established. It is true in the story. |
| Draft | Still being worked out. |
| Speculative | An idea that may or may not make it in. |
| Retconned | Was canon, then changed. The old version is kept. |
| Non-canon | Outside the story's continuity. |
Set it in the **Story** tab of the inspector, under **Canon**: click a status and it applies at once. The Codex shows the status as a badge on each page.
Canon status is used in three places:
* the [continuity checks](#continuity-checks) warn when a canon scene links to something retconned or non-canon;
* the published wiki can be limited to **Only canon pages and passages**, see [Publishing](/docs/modules/publishing);
* the [AI agent](/docs/guide/ai) is told to respect it, and asks before changing it.
A note that is [locked for review](/docs/modules/editorial) can't have its canon status or its reveal changed until it is unlocked.
### Retcons keep their history [#retcons-keep-their-history]
Choosing **Retconned** opens a short form instead of applying straight away.
1. Say what changed and why: "Her brother survives: Book 3 needs him." The reason is required.
2. Optionally pick the release it changed in, under **Changed in…**. The list appears once the project has releases.
3. Press **Retcon**.
Plotra saves the note's text as it stands as a named version, "Before retcon:" followed by your reason, and adds an entry to the retcon history under the status buttons. Each entry shows the reason, the release it changed in, what the status was before, who did it and when. **old text in History** opens the History panel, where the saved version is kept. See [Version history](/docs/guide/collaboration#version-history).
A note can be retconned more than once; every entry is kept, newest first. Moving a note away from **Retconned** later doesn't remove its history.
### One block can differ from its note [#one-block-can-differ-from-its-note]
A character page can be canon while one line on it is still speculative. Put the cursor in a block and press `⌘⌥T` to give that block its own canon status. See [Block tags](#block-tags).
## Releases [#releases]
A **release** is whatever your story ships in: a book, a chapter of a web serial, an episode, a season, an issue, a game patch, a campaign session. Releases have an order, and the order is what "before" and "after" mean everywhere on this page.
### The Release roadmap view [#the-release-roadmap-view]
Open it from the ribbon (**Releases**) or with "Open release roadmap" in the command palette. It needs the **Releases & reveals** module.
The toolbar:
| Control | What it does |
| --------------- | ------------------------------------------------------------------------------------------------ |
| **Release** | Adds a release at the end of the list. |
| **Channels** | Opens Project settings, where the reveal channels are edited in the **Reveals & languages** tab. |
| **World as of** | Sets the [spoiler horizon](#the-spoiler-horizon). |
Below it is a table: one row for each release, one column for each channel. A cell lists what the audience learns in that release, through that channel.
### A release [#a-release]
A new release is named after its kind and its number ("Book 3", "Session 4"). Its kind starts as the one that suits the project type: a book for a novel, a session for a campaign, an episode for a screenplay. See [Project types](/docs/reference/project-types).
Everything about a release is edited in its row:
| Part | What it does |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Title | Click to rename. Up to 80 characters. |
| **Earlier** / **Later** | The arrows move the release up or down the order. |
| **Delete release** | Removes it, after a confirmation. |
| Kind | Book, Chapter, Episode, Season, Issue, Volume, Patch, Session, Marketing beat or Release. A label only: it changes nothing else. |
| Date | The planned or actual date. Optional. |
| **Ships** | A folder or chapter from the binder: "this folder is Book 2". Everything inside it is then revealed by this release, with no further tagging. "nothing from the binder" is the default. |
When a release ships a folder, the row shows the folder's word count and a button that opens it. If two releases ship the same folder, the earlier one counts.
A **Released** badge appears once the release has been cut in the **Review & editorial** module, which snapshots every note for the changelog. See [Review and editorial](/docs/modules/editorial).
A project can hold 500 releases.
**Deleting a release.** Notes tagged as revealed by it go back to not revealed. Passages tagged with it keep the tag, shown as "A removed release": they stay hidden under every horizon and are left out of exports until you retag them.
## Reveals [#reveals]
A reveal says *when the audience learns something*, and optionally *where*.
### Revealing a note [#revealing-a-note]
In the **Story** tab of the inspector, under **Revealed to the audience**:
| Control | What it does |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The first list | The release that reveals the note: "In Book 2". The empty choice reads "Not revealed yet", or "With its folder (Book 2)" when a folder above the note already reveals it. |
| The second list | The **channel**: where the audience learns it. Shown once the note is revealed. "Channel not specified" is the default. |
| **Truth** / **Belief** | The knowledge layer. See [Who knows what](#who-knows-what). |
Until the project has a release, this section offers a link to the roadmap instead.
The roadmap sets the same thing from the other side:
* **Reveal a note** in a cell picks a note and tags it with that release and channel.
* The cross beside a note in a cell (**Remove from this release**) clears its reveal.
* The **Not revealed yet** list at the bottom has a **Reveal in…** menu on each note. It lists the first 60 notes and counts the rest. Folders, chapters, canvases and timelines are not listed.
### Channels [#channels]
A channel is where a reveal happens: the chapter text, a trailer, an interview, a handout to your players. A project starts with Main text, Trailer, Interview, Social post and Supplementary story. Change them in **Project settings**, the **Reveals & languages** tab: up to 20, each up to 40 characters. See [Project settings](/docs/guide/project-settings#reveals-and-languages).
Channels are labels for planning. They don't change what the spoiler horizon hides. A reveal with no channel, or with a channel that has since been removed, appears in a **No channel** column at the end of the roadmap.
### How Plotra decides when a note is revealed [#how-plotra-decides-when-a-note-is-revealed]
Nearest rule first:
1. The note's own reveal tag.
2. Otherwise, the closest note above it in the binder that has a reveal tag or that a release ships. A scene inside the "Book 2" folder is revealed by Book 2.
3. Otherwise, it is **not revealed**. The audience hasn't been told.
A block inside a revealed note is revealed with it, unless the block has its own tag: a later release, or "never".
In the campaign sample, each session is a release that ships that session's folder, so its scenes need no tags. The reeve's character page is revealed in Session 1, the paragraph about his second ledger is tagged for Session 3, and the game master's notes on how he behaves when cornered are tagged **Never**.
### Block tags [#block-tags]
A block tag gives one block, or several, settings of its own. It is how you mark a secret inside a page the audience otherwise knows.
To tag:
1. Put the cursor in a block, or select several.
2. Press `⌘⌥T`, run "Tag block (canon, reveal, fact-check)…" from the command palette, or use **Tag the selected block** in the **Story** tab.
3. Set the fields and press **Apply**.
The dialog shows only the fields of the modules that are on. With none of the three on, it says so and offers nothing to set.
| Field | Module | Choices |
| -------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| **Canon** | World bible | "Same as the note", or any canon status. |
| **Revealed** | Releases & reveals | "With the note", "Never (the audience isn't told)", or a release. |
| **Where** | Releases & reveals | The channel. Shown only when a release is chosen. |
| **Layer** | Releases & reveals | Truth, or Belief: what people are led to believe. |
| **Fact-check** | Research & sources | "Not a claim", Unverified, Verified or Disputed, and then a **Source**. See [Research and sources](/docs/modules/research). |
Anything left at its first choice follows the note. **Clear tags** removes every tag from the selected blocks. With several blocks selected, the dialog opens with the first block's tags and **Apply** writes them to all of them.
A tagged block has a coloured line down its left side and small labels at its right: the canon status, the release and channel or "Never revealed", "Belief", and the fact-check status. Click a label to open the dialog for that block.
The **Story** tab lists the note's tagged blocks under **Tagged passages**, each with the start of its text and its tags. Click one to edit it; the note has to be open.
Things to know:
* Tags belong to the block. They travel with it when it is moved, copied or restored from a version.
* Tagging needs edit access to the note. Tags are applied directly, even in suggesting mode.
* The roadmap, the Story tab and Secrets & setups read tags from the saved copy of the note, which is updated a few seconds after you stop typing. A new tag takes that long to appear there.
* Up to 500 tagged blocks per note are indexed.
## The spoiler horizon [#the-spoiler-horizon]
The spoiler horizon shows the project as the audience knows it once a given release is out. Everything revealed by that release or an earlier one is known; everything else is not.
### Setting it [#setting-it]
Choose a release under **World as of** in the Release roadmap toolbar. "Everything (no spoiler filter)" turns it off.
While a horizon is on:
* the status bar shows **World as of** and the release's title. Click the name to open the roadmap; click the cross to show the whole world again;
* the release's row in the roadmap is tinted and marked with an eye.
The horizon is remembered in your browser, for each project. Your co-writers set their own, and so does each of your devices. If the release is deleted, the horizon turns off.
### What it hides [#what-it-hides]
| Where | What happens |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Binder | Notes the audience doesn't know are dimmed and marked with a closed eye. A folder stays lit if anything inside it is known. Dimmed notes still open. |
| Editor | A block tagged for a later release, or **Never**, is blurred. Hover over it or put the cursor in it to read and edit it. |
| Outline | Lists only known notes and the folders that hold them. |
| Codex, Graph, Timeline | Leave out notes the audience doesn't know. |
| Quest designer | Leaves out quests the audience doesn't know. |
| Read | Leaves out unknown notes, and blocks tagged for later or never. A folder shown only for what is inside it keeps its title and loses its own text. |
| Secrets & setups | The middle column of **Knowledge layers** becomes "Told by this point". |
| Export | The export dialog says "As of" the release and exports only what is revealed by then, in every format. |
| Publish | The Publish view starts from the same release, and has its own **World as of** choice. See [Publishing](/docs/modules/publishing). |
| AI agent | Answers "as of" a release when you ask it to. See [The AI agent](/docs/guide/ai). |
### What it does not hide [#what-it-does-not-hide]
* **The text of a dimmed note.** Open a note the audience doesn't know and its text is there, unblurred. Only blocks with their own later or "never" tag are veiled in the editor.
* **The Corkboard, Plot grid, Manuscript, Relationships and Canvas views.** They show everything.
* **Search, the quick switcher, the link picker and the Links tab.** They find and list every note.
* **The Release roadmap and the Continuity view.** They always work on the whole project.
* **Anything from another person.** See the warning below.
### Passages marked Never [#passages-marked-never]
A block tagged **Never** is hidden under every horizon. It is also left out of every file export and of the published wiki when no horizon is on, as is a block tagged with a release that has been deleted. The Read view with no horizon shows them, and so does a PDF, which is printed from the Read view: set a horizon before printing a copy for someone else.
### What it is for [#what-it-is-for]
* **Writing a recap or a blurb** for Book 2 without a detail from Book 4 slipping in.
* **Writing the next book** with a clear view of what the reader already knows.
* **Running a tabletop campaign:** set the horizon to the last session and you see what your players know. Build the wiki in the Publish view at that horizon and hand it to them: that is the player-safe version.
* **A public wiki** that only contains what has been revealed.
The spoiler horizon filters what *you* see while you work, and what goes into an export or a published wiki. It is not a permission. Someone you share the project with as a viewer can read all of it, and so can anyone with the project's read-only link, passages marked Never included. To keep unrevealed material from a person, give them the wiki or an export made at the horizon, or keep the secrets in a separate project.
## Who knows what [#who-knows-what]
The **Secrets & setups** view tracks knowledge inside the story. Open it from the ribbon (**Secrets**) or with "Open secrets & setups" in the command palette. It needs the **Releases & reveals** module. It has three tabs.
### Knowledge layers [#knowledge-layers]
A fact can be the **truth**, or a **belief**: a false version that people are led to believe, such as a lie, propaganda or an unreliable narrator. Set the layer of a note with the **Truth** / **Belief** buttons in the Story tab, and of a block in the tag dialog. Everything is truth until you say otherwise.
The tab sorts the world into three columns:
| Column | Holds |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| **True, but untold** | What is the case and the audience doesn't know yet. |
| **Told to the audience** | Everything a release reveals. Under a spoiler horizon it is **Told by this point**: what the audience knows as of that release. |
| **Believed** | Notes and blocks on the belief layer. |
Each entry shows the note, the start of the text for a tagged block, and the release that reveals it. Click one to open the note. Folders, chapters, scenes, canvases, timelines and dialogues are not listed as notes, though their tagged blocks are. Each column shows up to 200 entries.
### Who knows what [#who-knows-what-1]
For each secret, record which characters know it and the scene where they learn it. This is what catches "how does she know that?" in chapter 20.
To track a secret, fill in the line at the top, "A secret (any note)… is known by a character…", and press **Track**. A secret is any note that isn't a folder; it is usually a note written for the purpose, or a world entry.
Secrets are listed with the characters who know them. For each character:
| Column | What it records |
| -------------- | -------------------------------------------------------------------------- |
| Learned in | The scene or chapter where they find out. "Knew all along" is the default. |
| What they know | "The truth", or "A false version". |
| Note | How they find out, or what they think instead. |
The cross removes the entry. In the campaign sample, Sister Wenna learns who set the fire in the mill scene ("Saw him leave the yard with a lantern"), while the guard captain holds a false version: he was told it was an accident.
These entries feed the [continuity check](#continuity-checks) "Knows something before learning it" and the **Learns** column of the character sheets.
### Setups and payoffs [#setups-and-payoffs]
Track what you plant and where it pays off. **Setup** in the toolbar adds a row.
| Column | What it holds |
| ----------- | -------------------------------------------------------------------------- |
| Kind | Foreshadowing, Chekhov's gun, Clue, Red herring or Mystery. |
| What | A name for it: "Lamp oil on the reeve's cuffs". Up to 80 characters. |
| Set up in | The note where it is planted. "Not planted yet" until you choose. |
| Pays off in | The note where it pays off. "No payoff yet" until you choose. |
| Status | Open, Paid off or Dropped. Choosing a payoff marks the setup **Paid off**. |
| Notes | Anything else. |
An open setup shows how long it has been waiting: "open for 12 scenes" counts the scenes after the one it was planted in. **Only what's still open** hides the rest. The bin deletes a row.
Open setups, and payoffs that come before their setup, are also reported by the continuity checks.
## Continuity checks [#continuity-checks]
The **Continuity** view runs a set of plain rules over the project. Open it from the ribbon or with "Open continuity" in the command palette. It needs the **World bible** module. There is no AI in it, nothing leaves your project, and the same project always gives the same answer.
### What the checks read [#what-the-checks-read]
* **Scenes:** the **Story date**, **Duration**, **POV** and **Location** properties.
* **Characters:** the **Born**, **Died**, **Age** and **First appearance** properties.
* **Links:** every `[[` link, embed and note-valued property.
* **Plot threads:** which scenes are in a thread, and the scene it is **Resolved in**, from the Plot grid. See [Planning views](/docs/guide/planning-views).
* **Who knows what** and **Setups and payoffs**, from Secrets & setups.
* **Canon status.**
A character is *in* a scene when they are its POV, or the scene links to them.
Write story dates as `YYYY-MM-DD`, with a time if you need one. In a project with a calendar of its own, month names work too ("4 Frostmonth 312"). When the project has custom calendars, a **Calendar** menu in the toolbar chooses the one dates are read in. It starts as the calendar of the project's timeline and is remembered in your browser. See [Timeline and canvas](/docs/guide/timeline-and-canvas).
The checks can't find a problem in something you haven't recorded, and they don't read your prose. The line under the toolbar shows how many scenes have a story date.
### The rules [#the-rules]
Results are grouped as **Contradictions**, **Worth a look** and **Notes**.
| Rule | Group | Triggered when |
| ------------------------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Appears after death | Contradictions | A character is in a scene whose story date is after their **Died** date. |
| In two places at once | Contradictions | A character is in two dated scenes that overlap in time, counting each scene's **Duration**, and the scenes have different **Location** values. |
| Appears before birth | Worth a look | A character is in a scene that ends before their **Born** date. |
| Age doesn't match the timeline | Worth a look | A character's **Age** is a number that differs from the years between **Born** and their **First appearance** scene, or their earliest dated scene if that isn't set. Also when **Died** is before **Born**. |
| Closed plot thread referenced again | Worth a look | A scene is in a plot thread and comes later in the binder than the scene the thread was resolved in. |
| Knows something before learning it | Worth a look | A scene links to a secret, its POV character is recorded as learning that secret in another scene, and this scene comes first. Order is by story date when both scenes have one, otherwise by binder order. |
| Payoff comes before its setup | Worth a look | A setup's payoff note comes before its setup note in the binder. |
| Canon scene relies on something that isn't canon | Worth a look | A scene with the status Canon links to a note that is Retconned or Non-canon. |
| Setup still open | Notes | A setup with the status Open has a note it is planted in. The message counts the scenes since. |
| Story date can't be read | Notes | A scene's **Story date** is filled in and isn't a date in the chosen calendar. |
Scenes without a story date are skipped by the date rules. Two scenes need a location each to count as two places.
### Working through the results [#working-through-the-results]
Each result names its rule, explains the problem and has a button for each note involved: click one to open it. After fixing something, press **Check again** in the toolbar.
* **Rule** filters the list to one rule. It appears when more than one rule has results.
* **Dismiss**, shown when you hover over a result, hides one that is intentional. Dismissals are stored in your browser for that project: they are not shared with co-writers and don't follow you to another device.
* **Show dismissed** brings them back into the list, faded, each with a **Restore** button.
A dismissed result stays dismissed for as long as the same notes are involved.
### Continuity sheets [#continuity-sheets]
The **Character sheets** tab builds a sheet for each character from what the project already holds. Pick a character from the list on the left.
The heading shows their birth and death dates and how many scenes they are in. **Open page** opens the character's note.
**Through the story** lists every scene they are in, plus any scene where they learn something:
| Column | Shows |
| ------ | ------------------------------------------------------------------------------------------------ |
| Scene | The scene, with a **POV** badge when they are its point of view. |
| When | The scene's story date. |
| Age | Their age then, from **Born**. "dead" in red if the scene is after their death. |
| Where | The scene's location. |
| Learns | The secrets they learn in that scene, marked "(a false version)" when it is one, with your note. |
The scenes are in story order when every one of them has a date, and in binder order otherwise; the heading says which. Below the table, **Knew from the start** lists secrets with no scene, and **Track what … knows** opens Secrets & setups.
Beside the table are the character's properties and their relationships from the Relationships view; click a related character to see their sheet.
## The Story tab [#the-story-tab]
The **Story** tab of the inspector gathers a note's canon and reveal settings. It appears when **World bible**, **Releases & reveals** or **Research & sources** is on. "Show canon and reveals" in the command palette opens it.
| Section | Needs | Covered in |
| -------------------------------------------------------------- | ------------------ | ----------------------------- |
| **Canon** and the retcon history | World bible | [Canon status](#canon-status) |
| **Revealed to the audience**: release, channel, Truth / Belief | Releases & reveals | [Reveals](#reveals) |
| **Tagged passages** and **Tag the selected block** | Any of the three | [Block tags](#block-tags) |
Under the reveal, two lines explain the effect: which horizons hide the note, and, for a note with others inside it, that everything inside is revealed with it unless it has its own tag.
## Things to know [#things-to-know]
* Block tags are indexed a few seconds after you stop typing, so the views lag slightly behind the editor.
* Releases, reveals, who-knows-what entries and setups are shared with everyone on the project. The spoiler horizon, dismissed continuity results and the continuity calendar are stored in your browser.
* Deleting a note for good removes its who-knows-what entries. A setup that pointed at it stays, with that side empty.
* A [shared world](/docs/guide/links#shared-worlds) lends its characters, places and entries to another project. It doesn't lend its releases: the borrowing project's horizon doesn't apply to shared pages.
# Working together (/docs/guide/collaboration)
Write with a co-writer in the same scene, hand a draft to a beta reader, or let an editor suggest changes, and no file ever leaves the project. There is one draft, and everyone is looking at the latest one.
## Who can do what [#who-can-do-what]
Access works like sharing a document. It is set in two places and nowhere else.
**The workspace.** Everyone in a workspace can open and edit every project in it.
| Workspace role | Can |
| -------------- | ----------------------------------------------------------- |
| Member | Read, comment and edit in every project of the workspace |
| Admin | The same, plus manage members, project settings and sharing |
| Owner | The same as an admin; the person who created the workspace |
**The project.** A project can be shared with anyone by email. That includes people outside the workspace, who then see only that project.
| Project role | Can | Typical use |
| ------------ | ---------------------- | ------------------------------------------------------------ |
| Viewer | Read | A friend reading a draft |
| Commenter | Read and comment | A beta reader |
| Editor | Read, comment and edit | An editor or co-writer who shouldn't see your other projects |
If someone is both a workspace member and has a project role, they get whichever lets them do more.
There are no permissions on single notes or folders. Everything in a project follows the project. A viewer reads the whole project, unrevealed secrets included. If part of a story must stay hidden from someone, put it in a separate project, or give them an export or wiki made at a [spoiler horizon](/docs/guide/canon#the-spoiler-horizon).
All of these roles are on both plans of the hosted version. How many people you can add depends on the plan: Free allows 3 workspace members, counting the owner, and 5 guests on each shared project; Pro allows 25 members and 200 guests. A guest is someone a project is shared with who is not a member of the workspace. See [Plans and billing](/docs/guide/plans).
## Inviting people to the workspace [#inviting-people-to-the-workspace]
In the workspace's settings, under members, enter an email address and pick member or admin. They get an email with a link; when they accept, they are in.
## Sharing a project [#sharing-a-project]
Open **Share** in the project and add an email address with a role.
* If that address already has a verified account, they have access at once.
* Otherwise they get an email with a link. The access goes to the account that opens the link.
People a project is shared with find it on their **Shared with you** page.
To change a role or remove someone, use the same dialog. Removing access takes effect on their next request. If they have a note open, live editing stops for them within a few minutes.
### A read-only link [#a-read-only-link]
The Share dialog can also create one link for the project that opens without an account, for reading only. Anyone who has the link can read the project, so treat it like a public page. You can switch it off again, or make a new link, and the old one stops working.
## Writing at the same time [#writing-at-the-same-time]
Open the same note as someone else and you see their cursor and selection, with their name. Text from both of you is merged as you type; you don't take turns and nothing needs to be locked.
The status bar shows who is in the project. Viewers and commenters are connected read-only: they see changes live but can't type.
### If your connection drops [#if-your-connection-drops]
Keep writing. Your changes are kept in your browser and merged with everyone else's when the connection returns. This works for notes you have already opened in that browser. The status bar shows whether you are synced.
## Comments [#comments]
Select text and choose **Comment** (`⌘⌥M`). Comments are threads: people reply, and a thread can be resolved and reopened. The **Comments** tab in the inspector lists the threads for the open note.
Type `@` and a name to mention someone. The mention is highlighted; it does not send a notification yet.
## Suggestions [#suggestions]
Suggesting mode is track changes. Turn it on with `⌘⇧E`. What you type is marked as an insertion and what you delete as a deletion, and nothing is final until an editor accepts or rejects it from the Comments tab, one by one or all at once.
Only people who can edit can make suggestions. A commenter can comment but can't suggest.
## Version history [#version-history]
The **History** tab in the inspector keeps earlier versions of a note.
* **Save a version** yourself whenever you like, with a name if you want one ("Before the rewrite").
* Plotra also saves one **automatically** about every half hour while a note is being edited. The latest 40 automatic versions are kept. Versions you named are not removed.
* Open a version to preview it and see what changed between it and now.
* **Restore** brings a version back. The current text is saved as a version first, so a restore can be undone.
Version history works for canvases too.
## Review workflows [#review-workflows]
With the **Review & editorial** module on, a project gets its own list of stages in place of Draft, Revised, Final, for example Draft, Beta read, Edit, Proof. A stage can be **locked**, so only approvers can change notes in it, or need **approval** from named reviewers. The Reviews view collects what is waiting for you. This module is less tested than the rest of this page.
# The editor (/docs/guide/editor)
The editor is the page a note opens in. It stays out of the way while you write: there is no fixed toolbar, the formatting bar appears only when you select text, and everything else is one key away. What you type is saved as you type it, and it reaches everyone else who has the note open.
Scenes, chapters, notes, characters, locations, research notes, world entries and folders all open in the editor. Canvases, timelines and dialogues open in views of their own; see [Views](/docs/guide/views).
## The page [#the-page]
From top to bottom, a note shows:
* **A trail**: the folders the note sits in, then its kind. Labels appear here when they apply: **Read only** or **Can comment** when you can't edit, **Locked** when a review stage has locked the note, and **Suggesting** while your edits are tracked as suggestions (click it to edit directly again).
* **The title.** Type to rename the note. `Enter`, or `↓` at the end of the title, moves into the text. `Esc` puts the old title back. A title can be 200 characters long; an empty one goes back to what it was.
* **The text.**
An empty note shows a line of grey text in place of a bare cursor: a way in that fits the kind of note ("Open on a line of dialogue."), followed by the two keys worth knowing. The same note always shows the same line. To get the plain "Start writing." back, open **Customize** and switch off **Suggest a way in when a note is empty**.
### How the page looks [#how-the-page-looks]
The typeface and spacing of the page are yours, not the project's. Open **Customize** from the **More** menu in the ribbon, or run "Customize: ribbon, inspector and the look of the page" from the command palette, and go to **The page**.
| Setting | Choices | Starts as |
| ---------------- | ---------------------------------- | ------------- |
| **Typeface** | Serif, Sans-serif, Typewriter | Serif |
| **Text size** | Small, Medium, Large, Extra large | Medium |
| **Line width** | Narrow, Normal, Wide | Normal |
| **Line spacing** | Tight, Normal, Relaxed | Normal |
| **Paragraphs** | Space between, First line indented | Space between |
These are saved with your account, so they are the same in every project and on every device, and nobody else's screen changes. They only affect the page you write on: printed and exported pages have their own formats. A note in a script format keeps that format's layout whatever you choose here.
## Blocks [#blocks]
A note is made of blocks: a paragraph, a heading, a list item, a table. Type `/` at the start of a line or after a space to open the block menu, keep typing to filter it, and press `Enter` to insert.
| Block | What it is | Also made by |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| **Text** | A paragraph. | |
| **Heading 1**, **Heading 2**, **Heading 3** | Headings. They build the note's outline in the inspector and can be linked to. | `#`, `##` or `###` and a space; `⌘⌥1`, `⌘⌥2`, `⌘⌥3` |
| **Bulleted list** | | `-` or `*` and a space |
| **Numbered list** | | `1.` or `1)` and a space |
| **To-do list** | A list with a checkbox on each line. Click the box to tick it; a ticked line is greyed and struck through. | `[ ]` and a space, or `[x]` for one already ticked |
| **Quote** | An indented, italic passage. | `>` and a space; `⌘⇧.` |
| **Callout** | A shaded box with a light-bulb icon, for an aside. | |
| **Table** | Starts with three columns and three rows. See [Tables](#tables). | |
| **Image** | A picture from a web address. See [Images](#images). | |
| **Divider** | A horizontal line, for a scene break. | `---` or `___` |
Below the blocks, the menu has a **Links** group:
| Item | What it does |
| ---------------- | -------------------------------------------------------------------------------------------------------------- |
| **Link to note** | Starts a link to another note, the same as typing `[[`. |
| **Embed note** | Shows another note inside this one, the same as typing `. |
Two more groups appear when they apply. Where AI is on, an **AI** group offers **Continue writing**; see [AI](/docs/guide/ai). In a note written in a script format, the format's own elements (scene heading, character, dialogue) come first; see [Scripts](/docs/modules/scripts).
Inserting a block into an empty line replaces that line. Otherwise the new block goes below the one you are in.
A few things about blocks that save keystrokes:
* `Enter` in an empty heading turns it back into a paragraph.
* `⌘↵` starts a new paragraph below the block you are in, and `⌘⇧↵` one above it. This is how you get out of a table, a quote or a callout.
* A note always ends with an empty paragraph, so there is somewhere to click after a table or an image.
## Formatting text [#formatting-text]
Select some text and a toolbar appears above it. From left to right:
| Control | What it does | Keys |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----- |
| **AI** | Rewrites, shortens, expands or changes the tone of the selection. Only where AI is on. See [AI](/docs/guide/ai). | `⌘J` |
| The block's type (for example **Text**) | Turns the selected blocks into another type: Text, Heading 1 to 3, Bulleted list, Numbered list, To-do list or Quote. | |
| **Bold** | | `⌘B` |
| **Italic** | | `⌘I` |
| **Underline** | | `⌘U` |
| **Strikethrough** | | `⌘⇧X` |
| **Highlight** | Marks the text in yellow. | `⌘⇧H` |
| **Code** | Sets the text in a fixed-width face on a grey ground. | `⌘E` |
| **Link** | Links the selection to a web address. See [Web links](#web-links). | `⌘K` |
| **Comment** | Starts a comment on the selection. See [Comments](/docs/guide/collaboration#comments). | `⌘⌥M` |
With the **Production** module on, the toolbar has one more button, for tagging the selection as a prop, a costume or another breakdown element; see [Production](/docs/modules/production).
The toolbar is not shown in a note you can't edit.
### Markdown shortcuts [#markdown-shortcuts]
If you know Markdown, type it and the editor formats as you go.
| Type | You get |
| ----------------------------- | --------------- |
| `**text**` | Bold |
| `*text*` or `_text_` | Italic |
| `***text***` | Bold and italic |
| `~~text~~` | Strikethrough |
| `==text==` | Highlight |
| `` `text` `` | Code |
| `[text](https://example.com)` | A link |
The block shortcuts (`#`, `-`, `1.`, `[ ]`, `>`, `---`) are in the table under [Blocks](#blocks).
### Typography [#typography]
The editor sets the punctuation a manuscript expects.
| Type | You get |
| ----------- | ------------------------------------------ |
| `"` and `'` | Curly quotes, opening or closing as needed |
| `--` | An em dash |
| `...` | An ellipsis |
| `->` | An arrow |
| `(c)` | A copyright sign |
### Web links [#web-links]
Select text and press `⌘K`, or choose **Link** in the toolbar. A small box asks for the address ("Paste link") and the text to show ("Text to display"). A web address that you paste, or type and follow with a space or `Enter`, becomes a link on its own.
Put the cursor in a link to get **Edit link**, a button that opens it in a new browser tab, and **Remove link**.
## Links to other notes [#links-to-other-notes]
Type `[[` and start typing a note's name. Pick one from the list and the link is made. If no note has that name, the list offers to create it.
Type `.
## Tags in the text [#tags-in-the-text]
Write `#` followed by a word anywhere in the text and the note carries that tag: `#subplot`, or nested with a slash, `#subplot/romance`. The `#` has to come at the start of a line or after a space, and the tag can't be only digits, so "chapter #3" doesn't make one.
Tags written in the text are listed in the inspector under **Tags** as "In the text", and they count in the tags pane beside the ones you add as a property. See [Tags](/docs/guide/vault-and-binder#tags).
## Tables [#tables]
Insert a table from the block menu. It starts at three by three. Click inside it and a small toolbar appears above its top-left corner:
| Button | What it does |
| ----------------- | ------------------------------------------ |
| **Row above** | Adds a row above the one the cursor is in. |
| **Row below** | Adds a row below it. |
| **Column** | Adds a column. |
| **Delete row** | Removes the cursor's row. |
| **Delete column** | Removes the cursor's column. |
| **Delete table** | Removes the whole table. |
A table that is wider than the page scrolls sideways.
## Images [#images]
Choose **Image** in the block menu and a prompt asks for the **Image URL**. The address has to start with `http://` or `https://`; anything else is ignored.
The editor doesn't upload pictures from your computer, and an image file pasted or dropped into the text is not inserted. An image is shown from the address you give, so it disappears from the note if that address stops working.
An image is centred and scaled to fit the page. There is no caption or resizing.
## Moving blocks [#moving-blocks]
Hold the pointer over a block and a handle appears in the margin to its left.
* **Drag** the handle to move the block. A line shows where it will land.
* **Click** the handle to select the whole block. A selected block is tinted. Selected blocks move together when you drag one of them, and `⌘⌥T` tags all of them at once.
* A list item takes the items indented under it along.
Handles are on top-level blocks only: a row or a cell of a table can't be dragged by itself. They are not shown in a note you can't edit.
## Block tags [#block-tags]
A single block can say something different from its note: a line that is still speculative on a page that is canon, a paragraph that isn't revealed until a later book, a claim that needs a source.
Put the cursor in a block, or select several, and press `⌘⌥T` (the command is "Tag block (canon, reveal, fact-check)…"). The dialog sets the block's **Canon** status, when and where it is **Revealed**, its **Layer**, and its **Fact-check** state with a **Source**. Which of these are offered depends on the modules that are on. **Clear tags** removes them all.
A tagged block has a coloured line down its left side and small labels at its right. Click a label to change the tags. Under a [spoiler horizon](/docs/guide/canon#the-spoiler-horizon), a block the audience hasn't been told about yet is blurred until you point at it or put the cursor in it.
Tags belong to the block, so they travel with it when it is moved, copied or restored from a version. They are applied directly, even while you are suggesting. What the tags mean is covered on [Canon and the spoiler horizon](/docs/guide/canon#canon-status) and [Research](/docs/modules/research).
## Focus mode [#focus-mode]
**Focus mode** (`⌘⇧F`) hides the ribbon, the binder, the inspector and the status bar. If the window is split, the pane you are writing in fills it; the other panes come back when you leave.
Leave with `Esc`, or with the **Leave focus (Esc)** button that appears at the bottom right when you move the pointer.
You can also turn it on from **More** in the ribbon.
## Typewriter scrolling [#typewriter-scrolling]
**Typewriter scrolling** (`⌘⇧T`) keeps the line you are writing in the middle of the pane, so your eyes stay in one place and the text moves instead. It works together with focus mode or without it. Turn it on from the command palette or from **More** in the ribbon, where it shows a tick while it is on.
Focus mode, typewriter scrolling and suggesting are switches for the sitting: all three are off again when you reload the page.
## Word counts [#word-counts]
The status bar at the bottom of the window counts as you type.
| Shown | What it counts |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **words** and **chars** | The open note. Characters include spaces but not line breaks. |
| **words in project** | Every note that isn't in the trash, as last saved. It follows a little behind your typing. |
| **this session** | The words you have typed since you opened the project, against your session goal if you set one. Click it for [writing stats and goals](/docs/guide/writing-goals). |
A word is a run of letters or digits; an apostrophe or a hyphen inside it doesn't split it, so "don't" and "well-known" are one word each. The text of an embedded note isn't counted in the note that embeds it.
The **Properties** panel of the inspector shows the same counts for the open note, with a **Reading time** worked out at 230 words a minute.
## Saving and working offline [#saving-and-working-offline]
There is no save button. Every change is sent to the server as you make it, and a copy of each note you open is kept in your browser.
The status bar shows where things stand:
| State | Meaning |
| --------------- | ----------------------------------------------------------------- |
| **Synced** | Every change is on the server. |
| **Connecting…** | Reaching the collaboration server. |
| **Offline** | Changes are kept on this device and sync when you're back online. |
While you are offline you can keep writing in any note you have opened on this device before. Its tab shows a dot, like an unsaved file, until the changes have gone up. When the connection returns, your changes and everyone else's are merged; see [If your connection drops](/docs/guide/collaboration#if-your-connection-drops).
A note you have never opened on this device can't be shown offline. It says: "Can't reach the collaboration server, and this note isn't saved on this device yet. Retrying…", and opens once the connection is back.
The text is what works offline. Changes to the binder (a new note, a rename, a move, a property) need the server. If one is still on its way when you close or reload the tab, the browser asks before leaving.
To go back to an earlier state of a note, use its [version history](/docs/guide/collaboration#version-history).
## When you can't edit [#when-you-cant-edit]
What the editor lets you do follows your role in the project; see [Roles and permissions](/docs/reference/roles-and-permissions).
| You are | The trail shows | What changes |
| --------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A viewer | **Read only** | The text and the title can't be changed. No formatting toolbar, no drag handles, no checkboxes to tick. Links, previews and embeds work as usual. |
| A commenter | **Can comment** | The same, except that selecting text shows a **Comment** button beside it. |
| An editor, in a locked note | **Locked** | A note in a locked review stage can only be changed by its approvers. Everyone else can read and comment. See [Review and editorial](/docs/modules/editorial). |
With the **Review & editorial** module on, the button beside a selection also offers reactions, for editors as well as commenters.
## Things to know [#things-to-know]
* There is no fixed toolbar and no right-click menu of the editor's own. Everything is in the block menu, the selection toolbar and the shortcuts.
* An embedded note can itself contain embeds, two levels deep. Past that it shows "Embedded too deeply to show here."
* Every shortcut on this page is listed, with the ones you can change, on [Keyboard shortcuts](/docs/reference/keyboard-shortcuts).
# Getting started (/docs/guide)
This guide takes you from signing up to your first scene. Read it in order the first time. After that, the headings are the things you will come back for.
No account yet? It is free, with every feature and no card.
Create your free account
## Signing up and signing in [#signing-up-and-signing-in]
To create an account, give three things:
| Field | Rule |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| **Your name** | Up to 80 characters. It is your byline: co-writers see it on your cursor, your comments and your changes. |
| **Email** | The address you sign in with, and where invitations and notifications go. |
| **Password** | At least 8 characters. The eye button shows what you typed. |
Then press **Start writing**.
Where the server has Google sign-in set up, as the hosted version does, **Continue with Google** is above the form and does the same job without a password. A self-hosted Plotra without Google credentials shows only the email form.
To come back, use **Sign in** with the same email and password, or the same Google account.
Things to know:
* The sign-in form has no "forgot password" link. Keep your password somewhere safe.
* If you opened a link to a project or an invitation before signing in, you are taken there once you have.
* On the hosted version, sign-in is limited to 5 tries a minute and sign-up to 5 an hour, to slow down guessing.
## Workspaces and projects [#workspaces-and-projects]
* A **workspace** is you, or you and your team. Its members can open and edit every project in it.
* A **project** is one story or one world: a novel, a series, a campaign.
A new account has neither, so the first thing Plotra asks for is a workspace name. The field is already filled in with "*Your first name*'s workspace". Press Enter to accept it, or type your own (up to 80 characters). The workspace's web address is made from the name. You can rename the workspace later.
To add another workspace later, use the workspace switcher at the top of the projects page. See [Your account and workspaces](/docs/guide/account).
Every project has a **type** (novel, web serial, tabletop RPG, screenplay and so on). The type decides which tools are switched on to begin with and what a new scene looks like. You can change all of it later in the [project settings](/docs/guide/project-settings). The eleven types are listed in [Project types](/docs/reference/project-types).
## Three ways to start a project [#three-ways-to-start-a-project]
| Way | What you get | Where |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Answer a few questions** | A project built around your story: a first page with your character and place already linked, and a checklist of first steps. | A new account lands here. Later: **Start your story** in an empty workspace, or "answer a few questions" in the New project dialog. |
| **New project** | A blank project with one empty scene. | The **New project** button on the workspace's projects page. |
| **A sample** | A small finished project to look around in, with one mistake to find. | In an empty workspace, in the New project dialog, and in the questions under "What are you making?". |
A workspace also offers its own **templates** in the questions, once someone has marked a project as one. See [Templates](/docs/guide/project-settings#templates).
On the hosted Free plan a workspace holds 10 projects, samples included. When it is full, Plotra says so and no project is made. See [Limits](/docs/guide/quotas).
## The cold open [#the-cold-open]
The cold open is the set of questions at `/start`. It asks one thing at a time, and each answer becomes a note. On a wide screen a small graph beside the questions shows the notes appearing and linking up.
Every question has **Continue**, **Skip this** and **Back**. Enter answers the question. A skipped question is simply left out of the project. **Skip, just give me a blank page** at the bottom makes the project at once from nothing. **Cancel** at the top takes you back to the workspace, if you came from one.
### The questions everyone gets [#the-questions-everyone-gets]
| Question | What it becomes |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Who is this story about?** | A character page. A name is enough (up to 80 characters). |
| **Where is *name* when it starts?** | A location page (up to 80 characters). |
| **What is *name* hiding, or what do they want?** | Choose **Hiding something** or **Wants something**, then write a line or two (up to 400 characters; Shift+Enter makes a new line). A secret becomes a note in a "Secrets" folder, with your character recorded as someone who knows it. A want becomes a plot thread on the first scene, and the character's **Arc**. |
| **What are you making?** | The project's type. **A novel** and **A tabletop campaign** lead; **Something else** shows the other nine. Some types carry a **Beta** tag. |
### The questions for your kind of project [#the-questions-for-your-kind-of-project]
After the type, Plotra asks one or two more in that medium's own words. The last one's button reads **Start writing**.
| Type | Question | What it does |
| ---------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Novel | **One book, or a series?** | A series gets a "Book 1" folder and a release called "Book 1" that you can mark reveals against. |
| Novel | **Whose eyes do we see it through?** (only if you named a character) | Your character, or **Someone else**, who then gets a character page and becomes the first scene's point of view. |
| Tabletop | **Who's at the table?** | The player characters, separated by commas. Up to eight, each with a page in a "Player characters" folder. |
| Tabletop | **What happens in session one?** | A line or two that becomes the top of your prep, and its synopsis. |
| Screenplay | **A film, a pilot or a series?** | Names the first folder "Act One", "Pilot" or "Episode 1". A series also gets a release called "Episode 1". |
| Screenplay | **Where does the first scene open?** | **INT.** or **EXT.** It becomes the scene heading. |
The other types have no extra questions.
### What the project starts with [#what-the-project-starts-with]
| Type | First page | Around it |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| Novel | "Chapter 1" with a scene called "Opening", which begins "*Mira* is in *the Salt Docks*." with both names as links. | "Characters" (your character as Protagonist), "Places", and "Secrets" if you gave one. |
| Tabletop RPG | A "Session 1" folder with "Session 1 prep". It ends with a line marked for the game master only, which players are never shown. | "Player characters", "NPCs", "Places", and a release called "Session 1". Chapters are called "Session" in this project. |
| Screenplay | "Opening scene", in screenplay format: the scene heading, an action line that brings your character on, their cue, and the cursor in their first line. | "Characters", "Places". Chapters are called "Sequence" in this project. |
| Any other type | One scene, in the type's own format. | "Characters", "Places", "Secrets". |
Also:
* The project is titled "Untitled: *who* in *where*", or just "Untitled". Rename it in the project settings.
* The scene's **POV** and **Location** properties already point at the notes made from your answers.
* If your answers made a release, a secret that someone knows or a game-master-only line, the **Releases & reveals** module is switched on, because that is where those live.
* The project opens on its first page with the cursor after the text that is already there.
* With every question skipped, you get the first page for that type, empty. If you skipped the type too, it is a novel.
## The new project dialog [#the-new-project-dialog]
**New project** on the projects page opens a short form. It makes a blank project: one scene called "Untitled scene", in the type's format, open with the cursor in it.
| Field | What it is |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Title** | Required, up to 120 characters. The project's web address is made from it. |
| **Type** | Novel / series and Tabletop RPG come first, then "Other kinds". The line under the field says which modules the type starts with and what format its scenes are written in. |
| **Create project** | Makes the project and opens it. |
| **Or open a sample** | The two samples, below the form. Choosing one makes it at once; the title and type above are not used. |
A project made this way starts with the standard ribbon (Graph, Codex, Outline, Draft, Read) whatever its type, keeps the app's own words for chapters, and has no checklist. Those three come from the cold open.
## Sample projects [#sample-projects]
A sample is a copy of your own: edit it, break it, delete what you like inside it. It counts as one project in the workspace. Each one opens on its first scene with a checklist called **Try it: fix the mistake**.
| Sample | Type | What is in it |
| -------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Romeo and Juliet** | Novel | Two parts and five scenes, the people and places of Verona, two houses as world entries, a timeline, three releases, two plot threads, a relationship map, a secret marriage with who knows it, setups and payoffs. One continuity slip: in "The Balcony", Romeo thinks of himself as a husband the night before "The Secret Wedding". |
| **Tabletop RPG campaign** ("Ashes at Carrow Ford") | Tabletop RPG | Three sessions as releases (two played, one in prep), player characters, NPCs with notes only the game master sees, places, a "Secrets (GM only)" folder, clues and a campaign timeline. One contradiction: Old Gar dies in the mill fire in session 2, and the guest list for session 3 still seats him. |
A sample has every module its type is meant for switched on, and its ribbon starts with the world tools: Graph, Codex, Releases, Secrets and Continuity.
The try-out's five steps:
1. **Open Continuity and read the report.**
2. **Go to the scene it names.** Click the scene's name in the report. It opens beside the report.
3. **Fix the line.**
4. **Check again.** Press "Check again" in Continuity. The problem is gone.
5. **See the world as of an earlier release.** Choose one under "World as of" in the Release roadmap. See [the spoiler horizon](/docs/guide/canon#the-spoiler-horizon).
## The screen [#the-screen]
From left to right:
| Part | What it is |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ribbon** | A strip of buttons. Each view button opens a view: graph, codex, outline and so on. See [The ribbon](#the-ribbon). |
| **Binder** | The tree of everything in the project, with a **Tags** tab beside it. See [The vault and the binder](/docs/guide/vault-and-binder). |
| **Panes** | The middle. Notes and views open here as tabs. You can split a pane right or down and drag tabs between panes. With nothing open, it shows the [project home](#the-project-home). |
| **Inspector** | The right sidebar, about the note that is open. Its tabs are **Note** (Properties and Outline), **Links**, **Story** and **Review** (Comments and History). Story is there when the World bible, Releases & reveals or Research module is on, and an **AI** tab when the AI agent is. |
| **Status bar** | Along the bottom: the workspace and project, word counts for the note and the project, the words you have typed this session, whether your changes are synced, who else is here, notifications and your account menu. |
Drag the edge of the binder or the inspector to resize it. The widths are remembered in your browser.
On a phone or a narrow window, the binder and the inspector open over the page as drawers, and the ribbon becomes a bar across the top with a **Views and commands** menu.
## The ribbon [#the-ribbon]
From top to bottom:
| Button | What it does |
| -------------------- | ----------------------------------------------------------------------------- |
| Arrow | Back to the workspace's projects, or to "Shared with you" if you are a guest. |
| **Toggle binder** | Shows or hides the binder (`⌘\`). |
| **Quick switcher** | Jump to a note by name (`⌘O`). |
| **Command palette** | Every command, searchable (`⌘P`). |
| The views | A few views, each with its name under the icon. |
| **More** | Every other view, and the settings below. |
| **Project settings** | Opens the [project settings](/docs/guide/project-settings). |
| **Toggle inspector** | Shows or hides the inspector (`⌘⇧\`). |
A project has twenty or more views. The ribbon starts with five, chosen by how the project was started, and the rest are under **More**. From there the ribbon is yours: right-click a view for **Move up**, **Move down**, **Remove from ribbon** and **Customize…**. Your arrangement is saved with your account, so it is the same in every project and on every device, and nobody else's ribbon changes. See [Customising the ribbon](/docs/guide/project-settings#customising-the-ribbon).
### The More menu [#the-more-menu]
| Section | What is in it |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Views | Every view that is not in your ribbon, grouped as **Plan**, **World**, **Read and publish**, **Team and progress** and **Tools**, with their shortcuts. |
| **More tools** | The modules this project has not switched on. Choosing one opens the prompt described below. Only people who manage the project see it. |
| **Saved layouts** | Switch between saved arrangements of panes (`⌘⇧L`). |
| **Focus mode** | Hides everything but the active pane (`⌘⇧F`). Escape leaves. |
| **Typewriter scrolling** | Keeps the line you are writing in the middle of the screen (`⌘⇧T`). |
| **Keyboard shortcuts** | The list of shortcuts (`⌘/`). |
| **Customize…** | The ribbon, the inspector, the look of the page, the project home and the guidance. |
## Write your first scene [#write-your-first-scene]
A new project opens on its first scene, so you can start typing straight away. For the next one:
1. In the binder, create a scene with the buttons at the top, or right-click a folder or a chapter and choose "New inside".
2. Click the scene. It opens in the editor.
3. Type. There is no save button: changes are saved as you write, and the status bar says **Synced**.
4. Type `/` at the start of a line or after a space for the block menu (headings, lists, tables, callouts, images). Select text for the formatting toolbar. Type `[[` to link to another note.
An empty note shows a suggestion in grey before you type, such as "Open on a line of dialogue." It is a way in, not text: it disappears with the first letter. To switch the suggestions off, open **Customize…** and clear "Suggest a way in when a note is empty".
If you go offline, the status bar says **Offline**. Your changes are kept on this device and sync when you are back.
## The getting-started checklist [#the-getting-started-checklist]
A project started from the cold open shows a small card in the bottom right corner: **Getting started**, with five steps and a count such as "2 of 5". Nothing is locked, and you can ignore it.
* A step is ticked when you do the thing, not when you press a button. Click a step to read how; the control it is about is ringed for a moment.
* Ticks are saved with your account. A step you did in one project is already ticked in the next, on any device.
* Finishing a step that is about a view pins that view to your ribbon.
* Click the title to fold the card away. The cross closes it for good; **Getting started** in your account menu brings it back, and so does **Customize…**.
* It is shown only to people who can edit the project, and not in focus mode.
The steps depend on what you are making:
| Novel, and every other type | Tabletop RPG | Screenplay |
| ---------------------------------- | ------------------------------ | ---------------------------- |
| Write your first 50 words | Write your first 50 words | Write your first 50 words |
| Link two notes | Link two notes | Link two notes |
| See your story as a graph | Write a line only you can see | Lay your scenes out as cards |
| Record a secret and who knows it | See what your players know | Start from a beat sheet |
| Set what readers know as of a book | Export a wiki for your players | Export to Fountain |
Some steps need a module. If it is off and you manage the project, the step shows a **Turn on …** button. If you can't switch modules on, the step is left out of your list.
## When Plotra offers a module [#when-plotra-offers-a-module]
A new project starts with few modules, so the screen is not twenty views wide on the first day. The others are offered where they become useful:
* a checklist step that needs one;
* **More → More tools** in the ribbon;
* the **Kinds** tab of the project settings, which offers the World bible.
Each of these opens the same prompt: "Turn on *module*?", with what the module is, the views it adds (they appear under **More**), and two buttons, **Not now** and **Turn on**. A module is switched on for everyone in the project, and nothing you have written changes. You can turn it off again in the project settings.
Only people who manage the project, the workspace's owner and admins, are offered modules. See [Modules](/docs/modules).
## The project home [#the-project-home]
When no note is open, the panes show the project's title, its word count and four blocks:
| Block | What it shows |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Carry on** | The four notes changed most recently, with their word counts. In an empty project: **Write the first scene**. |
| **This session** | Words typed this sitting, against your session goal if you have one. See [Writing goals](/docs/guide/writing-goals). |
| **Next, when you want it** | The next step of the checklist, with **Show me where** or **Turn on …**. Gone once the checklist is finished or closed. |
| Shortcuts | **New note**, **Open a note**, **All commands**, and **Writing stats and goals**. |
Choose which blocks are shown, and their order, under **Customize… → Project home**.
## Find anything [#find-anything]
| Keys | What it does |
| ----- | --------------------------------------------------------- |
| `⌘O` | Quick switcher: jump to a note by name |
| `⌘⇧O` | Search project |
| `⌘P` | Command palette: every command, searchable |
| `⌘/` | The list of keyboard shortcuts, where you can change them |
| `⌘\` | Show or hide the binder |
| `⌘⇧\` | Show or hide the inspector |
On Windows and Linux, use `Ctrl` where this guide says `⌘`.
Changed shortcuts are stored in your browser, so they don't follow you to another computer.
## Next [#next]
* [The vault and the binder](/docs/guide/vault-and-binder)
* [The editor](/docs/guide/editor)
* [Links and backlinks](/docs/guide/links)
* [Views](/docs/guide/views)
* [Project settings](/docs/guide/project-settings)
* [Modules](/docs/modules)
* [Working together](/docs/guide/collaboration)
* [Canon and the spoiler horizon](/docs/guide/canon)
* [Limits on the hosted version](/docs/guide/quotas)
* [Plans and billing](/docs/guide/plans)
# Links and backlinks (/docs/guide/links)
Links are what turn a folder of documents into a vault. Link a scene to the characters in it, and each character's page can tell you every scene they appear in. You stop searching your own draft for where someone was last seen.
Links are part of every project; no module needs to be on. Making one needs edit access to the note you are writing in.
## Making a link [#making-a-link]
Type `[[` in the editor. A list of notes appears; keep typing to narrow it, and press Enter. **Link to note** in the block menu (`/`) does the same.
| You type | You get |
| --------------------------------- | ------------------------------------------------------------------------------------ |
| `[[Mira Vale` | A link to the note called Mira Vale |
| `[[Mira Vale#Backstory` | A link to the "Backstory" heading inside that note, shown as "Mira Vale › Backstory" |
| `[[Mira Vale\|the archivist` | A link to Mira Vale that reads "the archivist" |
| `[[Mira Vale#Backstory\|her past` | A link to that heading that reads "her past" |
You pick the note from the list, so there is no need to type the closing brackets. The parts after `#` and `|` can be typed before you choose.
A link goes to a note, or to a heading in a note. There are no links to a single paragraph.
### The link picker [#the-link-picker]
* It searches names and **aliases**. A note found by an alias is marked "alias". Aliases are set in the Properties panel; see [The vault and the binder](/docs/guide/vault-and-binder).
* Exact matches come first, then names that start with what you typed, then names with a word that starts with it, then names that contain it. Up to 12 notes are shown, each with the folder it is in.
* Every kind of note can be linked except a folder.
* If no note has exactly that name, the last entry is **Create "…"**. It makes a new note with that name, without opening it, and links to it.
* After `#`, the list changes to **Headings in** the note: its headings of levels 1 to 3, and in a script its scene and act headings. Up to 30 are shown; keep typing to narrow them.
* With a [shared world](#shared-worlds), a second group, **From** and the world's title, offers up to six of its pages.
### Opening and previewing [#opening-and-previewing]
| Do this | And |
| ----------------- | -------------------------------------------------------------------------- |
| Hover over a link | A preview card opens after a moment. |
| Click | The note opens in the current tab. A heading link scrolls to that heading. |
| `⌘`-click | It opens in a new tab. |
| `⌘⌥`-click | It opens to the side. |
The preview shows the note's name and kind, its synopsis, and the start of its text: about 700 characters. For a heading link it starts below that heading. A preview is kept for 30 seconds, so text written in the last half-minute may be missing from it.
## Embeds [#embeds]
Put an exclamation mark in front, `![[Note`, or choose **Embed note** in the block menu, and the note's content is shown inside the page you are writing. The embed is a live, read-only view: change the original and the embed changes too.
* An embed is a block of its own, with the note's name at the top and an **Open** button. **Open** takes the same `⌘` and `⌘⌥` clicks as a link.
* A long note scrolls inside the embed, which is at most 480 pixels tall.
* An embed always shows the whole note. `![[Note#Heading` adds the heading to the label, and **Open** goes to it.
* Embeds can nest: an embedded note can show its own embeds. A third level reads "Embedded too deeply to show here."
* Pages of a shared world can be linked but not embedded.
* An embed counts as a link. The embedded note lists the page under Backlinks as "embedded".
## Backlinks [#backlinks]
The **Links** tab of the inspector shows, for the note that is open, three lists. Open it with `⌘⇧B` or "Show backlinks" in the command palette. Each list has a count and can be folded.
### Backlinks [#backlinks-1]
Every note that links to this one, once each, with the sentence or paragraph around each link so you can see why. Three other things count as a link here:
* an embed, shown as "embedded";
* a property that points at this note, shown as "as property" and the property's key, such as "pov". A scene whose **POV** is this character is a backlink;
* a citation of a research note. See [Research and sources](/docs/modules/research).
Notes in the trash are left out. An empty list reads "Nothing links here yet. Type \[\[ in another note."
### Outgoing links [#outgoing-links]
Every note this one links to, once each. Links through properties and embeds are included.
### Unlinked mentions [#unlinked-mentions]
Places where this note's name, or one of its aliases, appears as plain text without a link. This is how you find the three scenes where you wrote a character's name before you gave them a page.
Each mention shows the words around it. **Link** opens that note and turns the mention into a link. If the text was an alias or differs from the note's name, the link keeps reading as you wrote it.
* A mention is a whole word or phrase, in any capitalisation. "Mira" doesn't match "Miranda".
* Names and aliases shorter than two characters are ignored.
* **Link** is greyed out for a note you can't edit.
* If the text changed after the list was made, you are told "That mention has changed. Try again in a moment."
* The list holds up to 100 mentions, from up to 200 notes.
In all three lists, click a note to open it in the current tab, or `⌘`-click for a new tab.
### How fresh the lists are [#how-fresh-the-lists-are]
The list of links is rebuilt from the text a few seconds after you stop typing. The Links tab then refreshes every ten seconds while the window is visible. A new link takes a moment to show up as a backlink. A note keeps up to 500 links in the index.
## Renaming, trash and broken links [#renaming-trash-and-broken-links]
A link points at the note itself, not at its name.
| What happens | What the link does |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| The note is renamed | Every link to it shows the new name at once. A link with its own text, `[[Mira Vale\|the archivist`, keeps that text. |
| The note is moved | Nothing changes. |
| The note is moved to the trash | The link is struck through and can't be clicked, and an embed of it reads "You don't have access to this note." Restore the note and both work again. |
| The note is deleted for good, or you can't open it | The link reads **Restricted note** with a lock. An embed reads "You don't have access to this note." |
| A heading is renamed or removed | The link still shows the old heading and opens the note without scrolling. Headings are matched by their text, so make the link again. |
Because links follow the note, there is no "broken links" report to work through. Use the graph's orphans to find notes that nothing links to.
## The graph [#the-graph]
The graph view (`⌘G`) draws every note as a dot and every link as a line. "Open local graph of current note" in the command palette draws only the note you are in and what surrounds it. Filters, groups, orphans and the local graph are covered on [World views](/docs/guide/world-views).
## Shared worlds [#shared-worlds]
A project can use another project in the same workspace as its **world**: a book and its sequel, or a series, a show and a game, can share one set of characters and places.
### Setting it up [#setting-it-up]
In **Project settings**, the **General** tab, choose the project under **Shared world bible**. "None: this project keeps its own world" is the default. Changing it needs someone who manages the project. See [Project settings](/docs/guide/project-settings#shared-world-bible).
* Only other projects of the same workspace that you can open are offered.
* It goes one level deep. A project that itself uses a shared world can't be chosen, and a world's own world is not followed.
* A project can't be its own world.
### What you get [#what-you-get]
* **In the Codex,** a switch at the top between **This project** and the world's title. The world's characters, locations and world entries are listed with their properties and canon status. They are read-only here: edit them in their own project.
* **In the link picker,** the world's pages under **From** and the world's title, once you have typed something.
* **In the text,** a link to a shared page has a small planet beside it. Hovering shows its name and the world it is from. Click it to open the page in the Codex; `⌘`-click opens the Codex to the side.
Only characters, locations and world entries are shared. Scenes, notes, research and the world's releases stay in their own project.
### Limits [#limits]
* **Access follows the world project.** Someone who can open your project but not the world sees those links as **Restricted note**, and gets no world switch in the Codex.
* **No backlinks or graph.** Links into the shared world don't appear in the Links tab of either project, or in the graph.
* **No embeds and no hover preview** for shared pages.
* **The spoiler horizon doesn't apply** to shared pages: the Codex shows all of them, whatever release you are looking at.
* **If the shared world is set back to None,** existing links to its pages read **Restricted note**. Choosing the same world again brings them back.
# Notifications and activity (/docs/guide/notifications)
You don't have to keep checking a project to know what changed. Plotra tells you when something concerns you, and leaves the rest in the activity feed for when you want it.
## The bell [#the-bell]
The bell in the status bar (in the top bar on a phone) lists what other people did that concerns you. The number on it is how many you haven't read.
You get a notification when someone:
* mentions you in a comment with `@` and your name
* replies in a comment thread you started or took part in
* shares a project with you
* accepts a workspace invitation you sent
* asks you to review a note, as one of its required reviewers
* approves a note you sent for review, or asks for changes
You are never notified about your own actions, and one-click reactions don't notify anyone.
Click a notification to open the note it is about. If it is about a comment, the Comments tab opens on that thread. Notifications from your other projects are in the same list; clicking one takes you to that project. Opening a notification marks it read, and **Mark all read** clears the count.
A notification holds names and titles only: who, what kind of thing, and which note. It never contains the text of a comment or a document.
## The activity feed [#the-activity-feed]
Open **Activity** from the ribbon, or run "Open activity feed" from the command palette. It lists what happened in the project, newest first:
* notes created, renamed, moved to the trash and restored
* comments added
* versions saved with a name, and versions restored
* releases cut
* the project being shared, with the role but not the person's address
Everyone who can open the project sees the same feed. Titles are shown as they were at the time, so a renamed note appears under its old name in older rows. Click a row to open its note, if it still exists.
Typing isn't in the feed. For how much was written and when, see [Writing goals](/docs/guide/writing-goals).
## Email [#email]
Notifications can also be emailed. Open your account menu, choose **Your settings**, and under **Email notifications** pick one:
| Setting | What you get |
| -------------- | ------------------------------------------------------------------------------------------------------- |
| A daily digest | One email a day listing what you haven't read. No email on a day with nothing new. This is the default. |
| Each one | An email when it happens, up to twelve an hour. Anything past that goes into the next digest. |
| Off | No notification emails. |
Something you have already read under the bell is not emailed. Invitations and sharing emails are sent whatever you choose here, because they carry the link you need to get in.
Like the notifications themselves, the emails say who did what and where, with a link, and nothing from the text.
On the hosted version the number of notification emails a day is limited. On a busy day some may arrive in the next day's digest instead; nothing is lost from the bell.
### If you host Plotra yourself [#if-you-host-plotra-yourself]
The digest is sent when something calls `/api/cron/digest` with the `CRON_SECRET` you set. The repository includes a GitHub Actions workflow that does this once a day; any scheduler that can make an HTTP request works too. Without `CRON_SECRET` no digest is sent, and without `SMTP_URL` emails are written to the server log instead of sent.
# Planning views (/docs/guide/planning-views)
Five views show the structure of the story instead of one note at a time. The Outline is a table of everything. The Corkboard is a folder as index cards. The Plot grid sets scenes against plot threads. The Manuscript stitches a folder into one editable page. Read lays the same folder out as printed pages.
They all read the same notes as the binder and the editor. Change a title, a status or a synopsis in one of them and it changes everywhere. How to open each one, and how a view picks its folder, is in [Views](/docs/guide/views).
None of these views needs a module.
## Outline [#outline]
A table with one row for every note in the project. Open it from the ribbon, or run "Open outline" from the command palette. It always covers the whole project.
### Columns [#columns]
| Column | What it shows | Editable in place |
| ---------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------- |
| **Title** | The note's icon and title, indented as in the binder. | Yes. Type and press `↵` or click away. An empty title is not saved. |
| **Kind** | Scene, Chapter, Character and so on, in the project's own words. | No |
| **Status** | The note's workflow status. | Yes, from a list of the project's statuses. |
| **Synopsis** | The one-line summary. | Yes. Clearing it removes the synopsis. |
| Property columns | One column for each property you switch on. | Yes, with the same control as the **Properties** panel. |
| **Words** | The note's word count, as last saved. | No |
Press `Esc` while typing in a cell to put back what was there.
A property cell is editable only on a row whose kind has that property. A scene has a **POV**; a character does not, so its POV cell shows a dot.
To open a note, point at its row and click the arrow at the end of the title. `⌘`-click opens it in a new tab.
The bottom row counts the rows shown and adds up their words.
### Choosing the property columns [#choosing-the-property-columns]
Click **Columns** on the right of the toolbar and tick the properties you want. The list has every property defined for the built-in kinds, including your [custom fields](/docs/guide/vault-and-binder#custom-fields). The fields of world-entry types are not offered as columns. A new project shows **POV** and **Story date**.
Your choice is kept in your browser, for this project. It does not follow you to another computer, and your co-writers choose their own.
### Filters [#filters]
| Control | What it does |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Filter by title or synopsis** | Keeps rows whose title or synopsis contains the text. |
| **Kind** | One kind, or **All kinds**. |
| **Status** | One status, or **Any status**. |
| **Tag** | One tag, or **Any tag**. A tag also matches its nested tags: `place` matches `place/city`. The list appears once the project has tags. |
Filters combine. They are not saved: they reset when you close the tab.
### Sorting [#sorting]
Click a column heading to sort by it. Click again to reverse the order, and a third time to go back to binder order. **Title**, **Kind**, **Status**, **Words** and every property column sort; **Synopsis** does not.
* **Status** sorts in the order of the project's workflow, not alphabetically.
* A property that points at a note (a POV, a location) sorts by that note's title.
* Rows with no value for the property go last.
### Tree or flat list [#tree-or-flat-list]
With no filter and no sort, the outline is the binder's tree. Click the arrow before a title to collapse or expand what is inside it.
As soon as you filter or sort, the outline becomes a flat list with no indentation, so that every match is visible whatever folder it is in.
### Who can edit [#who-can-edit]
You can edit a row if you can edit that note. Otherwise its cells are greyed out. See [Roles and permissions](/docs/reference/roles-and-permissions).
### Under a spoiler horizon [#under-a-spoiler-horizon]
When a [spoiler horizon](/docs/guide/canon#the-spoiler-horizon) is on, the outline lists only what the audience knows by then, and the folders that hold it.
## Corkboard [#corkboard]
The notes inside one folder or chapter, as index cards in binder order. Open it from the ribbon, with "Open corkboard of current folder" from the command palette, or by right-clicking a folder in the binder and choosing **Corkboard**.
Canvases and timelines are not shown as cards. Everything else directly inside the folder is.
### A card [#a-card]
| Part | What it shows |
| ---------------------------- | --------------------------------------------------------------------- |
| Coloured strip along the top | The note's label, if it has one. Point at it for the label's name. |
| Number | The card's place in the folder. |
| Title | Click to open the note. `⌘`-click opens it in a new tab. |
| Dot | The status. Point at it for the name. |
| Body | The synopsis. Double-click to write or change it. |
| Foot | The word count, and **Open cards** when the note has notes inside it. |
To edit a synopsis, double-click the body of the card, type, and click away to save. `Esc` cancels. An empty card reads "Double-click to write a synopsis".
### Moving between folders [#moving-between-folders]
The trail at the top left starts with the project's name and ends with the folder you are in. Click any part of it to go there. Click the project's name for the top level of the binder.
**Open cards** on a card goes into that note and shows what is inside it.
### Reordering [#reordering]
Drag a card onto another card. Drop on its left half to put your card before it, on its right half to put it after. An orange bar shows where it will land.
The binder order changes with it, for everyone. A card moves within its own folder only; to move a note to another folder, drag it in the binder.
You can drag a card only if you can edit that note, and not while you are editing its synopsis.
### Adding cards [#adding-cards]
**Scene** and **Chapter** on the right of the toolbar add a new scene or chapter at the end of the folder, without opening it. They are greyed out if you cannot edit the folder.
An empty folder shows "No cards here" and a **New scene** button.
## Plot grid [#plot-grid]
Scenes down the side, in reading order. Plot threads across the top. Each cell says what happens to that thread in that scene. Open it from the ribbon, with "Open plot grid", or from a folder's right-click menu to see only that folder.
Reading down a column shows you where a thread goes quiet. Reading across a row shows you what a scene is doing.
### Rows [#rows]
Every scene and chapter inside the folder, at any depth, in binder order. Chapters are heading rows with no cells. A scene row shows the status dot, the title and the first two lines of the synopsis. Click a title to open the note in a new tab.
Other kinds of note are not rows.
### Threads [#threads]
Click **Thread** in the toolbar to add a plot thread. It is called "Thread 1", "Thread 2" and so on, and takes the first colour no other thread uses. A thread belongs to the project, so it is the same column in every plot grid, whichever folder the grid is open on.
* **Rename:** click the name at the top of the column, type, and press `↵`. A name can be 80 characters.
* Click the three dots beside the name for the rest:
| Option | What it does |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Colour dots | Changes the thread's colour. |
| **← Move** / **Move →** | Moves the column one place left or right. |
| **Resolved in** | The scene where the thread ends, or **Still open**. The list has the scenes in the grid. A scene in the thread after that point becomes a [continuity warning](/docs/guide/canon#continuity-checks). |
| **Delete thread** | Deletes the thread and every cell in its column, at once and without asking. |
Adding, renaming, moving and deleting threads needs edit access to the project.
### Cells [#cells]
Click a cell and write what happens to the thread in that scene. Click away, or press `⌘↵`, to save. `Esc` cancels. A cell holds up to 4,000 characters and shows its first five lines.
Writing in a cell puts the scene **in the thread**: the cell is tinted in the thread's colour. A scene can be in any number of threads.
| To do this | Do this |
| ----------------------------------------- | -------------------------------------------------- |
| Put a scene in a thread | Click the cell and write a note. |
| Keep the scene in the thread with no note | Clear the note's text. The cell shows a dot. |
| Take the scene out of the thread | Point at the cell and click the `×` in its corner. |
You can fill a cell if you can edit that scene.
Being in a thread is also what puts a scene in a thread's lane on a [timeline](/docs/guide/timeline-and-canvas#lanes).
### Empty states [#empty-states]
With no scenes, the grid shows "No scenes yet" and a **New scene** button. With scenes but no threads, the heading row reads "Add a plot thread to start the grid."
## Manuscript [#manuscript]
Every text note in a folder, one after another on a single page, and every one of them editable. Open it from the ribbon (its button is labelled **Draft**), with "Open manuscript (Scrivenings) of current folder", or from a folder's right-click menu.
Use it to read and revise across scene breaks without opening scenes one at a time.
### What is included [#what-is-included]
The folder itself and everything inside it, at any depth, in binder order: folders, chapters, scenes, notes, characters, locations and research notes. Canvases, timelines, dialogue trees and world entries are left out.
The toolbar shows the folder's name, the number of sections and their total word count. Folders are not counted as sections.
### Sections [#sections]
Each note is a section with a small line above it: its kind, its status dot, and **Open ↗** when you point at it. Click that line to open the note on its own to the right. `⌘`-click opens it in a new tab.
Folders and chapters get a large heading. Other notes get a smaller heading and a dashed line above. A folder shows only its heading, not the text of its own page.
### Editing [#editing]
Each section is the real note, in a live editor. What you type is saved to that note, your co-writers see it as you type, and their cursors show here too. The page uses your [page settings](/docs/guide/editor#how-the-page-looks): font, size and column width.
* If **suggesting** is on, your changes in the manuscript are suggestions, as in the editor.
* A section you cannot edit is read-only.
* Sections load as you scroll to them, so a long manuscript opens quickly. A grey block stands in for a section until it loads.
The Manuscript view shows everything, whatever the spoiler horizon is.
An empty folder shows "Nothing to stitch together" and a **New scene** button.
## Read [#read]
The folder laid out as pages, the way it would print. Open it from the ribbon, with "Read / print preview of current folder", or from a folder's right-click menu. **Export project…** with **PDF** chosen opens this view and prints it.
The toolbar shows the title, the number of pages and the word count.
### What is included [#what-is-included-1]
Every text note in the folder, at any depth, in binder order, up to 400 notes. The text is as last saved. Empty paragraphs are dropped.
The pages do not follow your typing. Click **Reload** to lay the pages out again from the latest saved text.
### Formats [#formats]
Choose the layout with the buttons on the right of the toolbar.
| Format | Layout |
| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Manuscript** | Standard submission format: a monospaced 12-point face, double-spaced, paragraphs indented half an inch. From the second page, the top right reads your surname, the title and the page number. Scenes are separated by a centred `#`. |
| **Book** | A typeset page: a serif face, justified and hyphenated, indented paragraphs. The title runs along the top in italics and the page number is at the foot. Scenes are separated by `⁂`. |
| **Screenplay**, **Stage play**, **Comic script**, **Audio script** | The script's own layout. Offered when part of the folder is written in that format, or when it is the project's format. See [Scripts](/docs/modules/scripts). |
When more than half of the notes with text in them are written in a script format, the view opens in that format. Otherwise it opens in **Manuscript**.
Pages are US Letter with one-inch margins. Screenplays and stage plays have an inch and a half on the left.
### The title page [#the-title-page]
The first page is always a title page.
* **Manuscript:** your name and email address at the top left, "about N words" at the top right (rounded to the nearest hundred), then the title in capitals and "by" your name.
* **Book:** the title in large type and "by" your name.
* **Scripts:** the title underlined in capitals, "Written by" and your name, your email address at the bottom left. If the folder was imported from a Fountain file with a title page, its Credit, Author, Source, Contact and Draft date are used instead.
The name and email address are those of whoever is looking at the view, not the project's owner. The title is the folder's name, or the project's name when the view covers the whole project.
### Headings and breaks [#headings-and-breaks]
* A chapter starts on a new page, and so does a top-level folder. Its title is a centred heading.
* In **Screenplay** and **Audio script**, folder and chapter headings are not printed: the script runs on from scene to scene.
* In a script, a horizontal rule is a page break. In a comic script, each comic page starts a new sheet.
* In a script, a scene heading or a character cue is never left alone at the foot of a page. It goes over with what follows it.
* Scripts number their pages at the top right, starting with "2." on the second page of the script itself.
### Printing and saving a PDF [#printing-and-saving-a-pdf]
Click **Print / PDF**. Your browser's print dialog opens with only the pages in it. Choose your printer, or choose "Save as PDF" to make a PDF file. The paper size is set to Letter.
There is no separate PDF export: this is how Plotra makes PDFs. Other formats are in [Import and export](/docs/guide/import-export).
### Under a spoiler horizon [#under-a-spoiler-horizon-1]
When a [spoiler horizon](/docs/guide/canon#the-spoiler-horizon) is on, the toolbar shows **As of** and the release's name. Notes the audience does not know yet are left out, and so are passages tagged for a later release. A folder kept only for what is inside it shows its title, not its own text.
### Empty state [#empty-state]
A folder with nothing to show reads "Nothing to read yet" with a **New scene** button.
# Plans and billing (/docs/guide/plans)
The hosted version of Plotra has two plans, **Free** and **Pro**. A plan belongs to a **workspace**, not to a person: everyone in a Pro workspace gets its limits, and nobody pays per seat.
No feature is locked behind Pro. Every view and module is on Free, with no time limit and no card. Pro is more room, more collaborators and hosted AI: $10 a month covers the whole workspace, so a writing group of five pays $2 each.
Start on Free
A team that needs more than Pro can arrange an **Enterprise** plan. Its limits, terms and price are worked out with the team: write to [sudhan@plotra.ink](mailto:sudhan@plotra.ink).
## The plans [#the-plans]
| | Free | Pro |
| ----------------------------------------- | --------------------- | ---------------------------------------------------------------- |
| Price | $0 | $10 a month, or $96 a year ($8 a month, 20% less), per workspace |
| Projects per workspace | 10 | Unlimited |
| Storage per workspace | 50 MB | 50 GB |
| One uploaded file | 10 MB | 100 MB |
| Workspace members | 3, counting the owner | 25 |
| Guests per shared project | 5 | 200 |
| Views, modules and features | All of them | All of them |
| AI agent on your own key or a local model | Yes | Yes, and it uses no credits |
| Hosted AI | No | 1,500 credits a month |
| Export | Always | Always |
* **Storage** counts uploaded files and version snapshots.
* A **member** belongs to the workspace and can open every project in it. The owner counts as one.
* A **guest** is someone a single project is shared with, as a viewer, commenter or editor, who is not a member of the workspace. A beta reader or an outside editor is a guest. See [Working together](/docs/guide/collaboration).
What happens when you reach a limit is in [Limits on the hosted version](/docs/guide/quotas).
## When Pro is worth it [#when-pro-is-worth-it]
Free is enough to write a book on. A workspace moves to Pro when one of these is true:
* **You have more than a few people.** Free holds 3 members and 5 guests per project. Pro holds 25 members and 200 guests, which covers a writing group, a full round of beta readers or a table of players, at the same $10.
* **You are running out of room.** Maps, reference images and version snapshots fill 50 MB quickly. Pro has 50 GB, a thousand times more, and takes files up to 100 MB.
* **You have more than 10 projects.** A series, its spin-offs and a campaign or two get there. Pro has no project limit.
* **You want the AI agent without setting anything up.** On Pro nobody in the workspace needs an API key or a local model.
The price is per workspace, so it doesn't rise as people join. Paying yearly is $96, which is $8 a month. A first payment is refunded in full if you ask within 14 days, and going back to Free deletes nothing, so trying Pro costs you nothing if it isn't for you.
## Hosted AI and credits [#hosted-ai-and-credits]
On Free, the AI agent runs on your own API key or on a model on your own computer. That works on Pro too.
Pro adds **hosted AI**: the agent runs on a model Plotra provides, so nobody in the workspace needs a key. It is paid for with credits.
* A Pro workspace gets **1,500 credits** each billing period, shared by everyone in it.
* **1 credit is 1,000 input tokens**, the text the model reads.
* **Output tokens count five times**: 1,000 tokens the model writes cost 5 credits.
* Credits **reset** when the billing period renews. Unused credits **don't roll over**.
* A run on **your own key or a local model uses no credits**.
For example, a run that reads 20,000 tokens of your notes and writes 2,000 tokens costs 20 + 10 = 30 credits.
On a hosted run, the notes the agent reads are sent to the model provider Plotra uses, not to a provider you chose. The privacy page on the Plotra site says more.
## Upgrading [#upgrading]
Open **Workspace settings → Plan & billing** and choose monthly or yearly. You are taken to a checkout page run by Creem. When the payment goes through, the workspace is on Pro.
Payments are handled by **Creem** (creem.io), which is the merchant of record. Creem charges your card, adds sales tax or VAT where it applies, and sends the invoice. Plotra never sees your card: it stores only a customer id, a subscription id and the state of the subscription.
## Cancelling [#cancelling]
Cancel at any time from **Workspace settings → Plan & billing**. The subscription stops renewing, and the workspace stays on Pro until the end of the period you already paid for. Then it goes back to Free.
## Going back to Free [#going-back-to-free]
A workspace that goes back to Free **keeps all its data**: every project, note, file and version.
* Nothing is deleted, and nothing becomes read-only.
* You can't add beyond the Free limits. A workspace with 14 projects keeps all 14 and can write in them, but can't create a 15th until it has fewer than 10.
* Hosted AI stops. The agent still works on your own key.
* **Export always works.**
## Sponsoring [#sponsoring]
Plotra also takes sponsorship through GitHub Sponsors. Sponsoring is a gift: it doesn't change a workspace's plan or limits. What the hosted version costs to run is in [the README](https://github.com/ItzSudhan/plotra#what-it-costs-to-run).
# Project settings (/docs/guide/project-settings)
A project's type is only a preset. Everything it chose for you can be changed: which tools are on, what a new scene looks like, what a "chapter" is called, the stages a note moves through. This page covers the **Project settings** dialog, section by section, and the **Customize** dialog, which holds what is yours alone.
| Dialog | What it changes | For whom |
| -------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------- |
| **Project settings** | The project: type, modules, workflow, words, labels, kinds, reveal channels, languages. | Everyone in the project sees the same. |
| **Customize** | Your screen: the ribbon, the inspector, the look of the page, the project home, guidance. | You alone, in every project. |
## Opening project settings [#opening-project-settings]
* The gear at the bottom of the ribbon, **Project settings**.
* The command palette (`⌘P`): "Project settings (type, modules, workflow)…".
* On a phone: the **Views and commands** menu in the top bar, then **Project settings**.
There is no save button. A change is saved when you make it: a text field saves when you press Enter or leave it. Everyone who has the project open gets the new settings at once.
## Who may change what [#who-may-change-what]
| Who | What they can change |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Workspace **owner** and **admins** | Everything. They are the people who "manage" the project. |
| Workspace **members**, and guests shared in as **editor** | The **Reveals & languages** tab, and the fields of the project's own kinds. Everything else is shown but greyed out, under the line "Only people who manage this project can change these." |
| Guests shared in as **viewer** or **commenter** | Nothing. They can open the dialog and read it. |
See [Roles and permissions](/docs/reference/roles-and-permissions).
## General [#general]
| Setting | What it does |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Title** | The project's name, up to 120 characters. It can't be empty. Renaming does not change the project's web address, so old links keep working. |
| **Logline or description** | One or two sentences, up to 2,000 characters. Used on the series bible and the public wiki. |
| **Type** | One of the eleven [project types](/docs/reference/project-types). Some types are marked "(beta)". |
| **New scenes are written as** | Prose, Screenplay, Stage play, Comic script or Audio script. |
| **Shared world bible** | Another project whose world this one borrows. |
| **Template** | Offers this project as a model for new ones. |
### Changing the type [#changing-the-type]
Changing the type changes which modules are on by default. A module you have switched on or off yourself stays as you set it. The format of new scenes follows the new type too, unless you have chosen one under **New scenes are written as**.
It does not touch anything you have written, the format of existing notes, the project's own words, or your ribbon.
### The format of new scenes [#the-format-of-new-scenes]
| Format | What a page is made of |
| ---------------- | ---------------------------------------------------------- |
| **Prose** | Paragraphs, headings and lists. |
| **Screenplay** | Scene headings, action, character, dialogue, transitions. |
| **Stage play** | Acts and scenes, stage directions, character and dialogue. |
| **Comic script** | Pages and panels with captions, dialogue and SFX. |
| **Audio script** | Character lines with delivery notes, sound and music cues. |
This is the default for scenes created from now on. A single note's format can be changed on the note itself. See [Script formats](/docs/modules/scripts).
### Shared world bible [#shared-world-bible]
A book series, a show and a game can share one world. Choose another project of the same workspace here, and its characters, places and entities appear in this project's codex and can be linked from any note. "None: this project keeps its own world" is the default.
* Only projects you can open are offered.
* It goes one level deep. A project that itself uses a shared world can't be chosen: link to that world instead.
* Who can see the shared pages is still decided by the world project's own sharing.
See [Shared worlds](/docs/guide/links#shared-worlds).
### Templates [#templates]
Tick **Offer this project as a template in its workspace** and the project appears in [the cold open](/docs/guide#the-cold-open), under "Or start in the shape of one of this workspace's templates".
A project started from a template is called "Untitled, from *template name*". It gets the template's:
* type, modules, words, labels and workflow;
* kinds and their fields, the fields of each kind of note, and custom calendars;
* folders and chapters, empty, with one empty scene to start in.
None of the template's text is copied: no scenes, no characters, no notes. The new project is an ordinary project, not another template, and it counts towards the workspace's project limit.
## Modules [#modules]
A list of the project's tool sets, each with a tick box, what it adds, and up to three tags:
| Tag | Meaning |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **default for this type** | The project's type starts with this module on. |
| **set by you** | Someone has switched it on or off by hand, so it no longer follows the type. Putting it back to the type's default removes the tag. |
| **Beta** | One of the newer modules: Script formats, Production, Interactive narrative or Localization. |
Tick a module to switch it on for everyone in the project. Its views appear under **More** in the ribbon. Untick it to switch it off: its views, commands and inspector sections go away, and everything made with it is kept for when you switch it back on.
**AI agent** is only in the list once the workspace has switched AI on. See [The AI agent](/docs/guide/ai#turning-it-on).
What each module adds is on the [Modules](/docs/modules) page.
## Workflow [#workflow]
Every note has a status, shown in the binder and the inspector. The status is a stage of the project's workflow. A project that hasn't set its own uses **Draft → Revised → Final**.
Three ready-made workflows are at the top. Clicking one replaces the stages:
| Preset | Stages |
| ------------------------------------------------ | ------------------------------------------------------------- |
| **Draft → Revised → Final** | The default. Nothing locked, nothing needs approval. |
| **Draft → In review → Approved → Locked** | Approved needs approval. Locked needs approval and is locked. |
| **Draft → Beta read → Edit → Copy-edit → Proof** | Proof needs approval and is locked. |
Or build your own. Each stage is a row:
| Control | What it does |
| -------------------------- | -------------------------------------------------------------------------------------------------- |
| The coloured dot | Pick the stage's colour. |
| The name | Rename the stage, up to 40 characters. |
| **Approval** | A note can only enter this stage once every required reviewer has approved it. |
| **Locked** | Notes in this stage are read-only for everyone but approvers. |
| **Move up**, **Move down** | Change the order. The first stage is the one new notes start in, and it is shown without a marker. |
| **Remove stage** | Takes the stage out. The last remaining stage can't be removed. |
| **Add a stage** | Adds "New stage" at the end. A workflow has between 1 and 12 stages. |
Notes in a stage you remove keep its name until you move them.
Reviewers and approvers are set in the **Reviews** view, which comes with the **Review & editorial** module. Without it, you can still mark stages as Approval or Locked here, but there is nowhere to name the reviewers. See [Review and editorial](/docs/modules/editorial).
## Words [#words]
Call the kinds of note what your medium calls them. A "Chapter" can be an "Episode", a "Session" or an "Act". The new word is used in the binder, the menus, the commands and every view, for everyone in the project.
Seven kinds can be renamed: **Folder**, **Chapter**, **Scene**, **Note**, **Character**, **Location** and **Research**. Type the new word (up to 30 characters) and press Enter. Clear the field to go back to the app's word. **Reset to the app's words** clears them all.
* Plotra makes the plural itself, by the usual English rules: "Sessions", "Stories", "Classes".
* Canvases, timelines and dialogues keep their names. World entries are named by their own kind.
* A project started from [the cold open](/docs/guide#the-cold-open) may already have a word of its own: a tabletop campaign calls chapters "Session", a screenplay calls them "Sequence".
Renaming a kind changes its label only. No note is changed.
## Labels [#labels]
Labels mark notes any way you like: "Needs research", "Subplot", "Cut?". They are separate from a note's status.
* **Add** one with the field at the bottom: a name of up to 40 characters. A project can have 24.
* **Colour** it with one of the seven dots.
* **Rename** it in place.
* **Delete** it with the bin. Notes that carry it lose it.
A note carries one label. Once the project has any, a **Label** field appears in the inspector's Properties. The label shows as a colour in the binder and on the corkboard.
## Kinds [#kinds]
Besides scenes, characters and places, a project can have kinds of its own: a Faction, a Spell, a Case. Each has its own icon, colour and fields, appears in the binder's **New** menu, and has a section in the Codex.
Kinds come with the **World bible** module. While it is off, this tab offers **Turn on World bible** to people who manage the project.
With it on, the tab lists the project's kinds and how many fields each has. **Edit** opens a kind; **New kind…** adds one. Anyone who can edit the project can do both. A world bible starts with nine: Faction, Object, Event, Species, Culture, Language, Religion, System and Theme. See [The world bible](/docs/guide/canon#the-world-bible).
## Reveals and languages [#reveals-and-languages]
Anyone who can edit the project can change this tab.
| Setting | What it does |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Reveal channels** | Where the audience can learn something: the text itself, a trailer, an interview. They start as Main text, Trailer, Interview, Social post and Supplementary story. Up to 20, each up to 40 characters. Used when you record a [reveal](/docs/guide/canon#reveals). |
| **Written in** | The language the project is written in, as a code. `en` unless you change it. |
| **Translated into** | The languages it is translated into, as codes such as `fr`, `de` or `pt-BR`. Up to 30. The Localization module keeps one translation per language. See [Localization](/docs/modules/localization). |
| **Citation style** | APA, MLA or Chicago, for references and the bibliography. APA unless you change it. See [Research and sources](/docs/modules/research). |
A language that isn't a code is refused: "Languages are codes like fr, de or pt-BR."
## What is not in the dialog [#what-is-not-in-the-dialog]
| Thing | Where it is |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| The fields of a kind of note (a scene's POV, a character's role, your own) | The inspector's **Properties**, on a note of that kind. See [Properties](/docs/guide/vault-and-binder#properties). |
| Custom calendars | The timeline. See [Timeline and canvas](/docs/guide/timeline-and-canvas). |
| The project's word target | The **Stats** view. See [Writing goals](/docs/guide/writing-goals). |
| Who the project is shared with | **Share project…** at the top of the binder. See [Working together](/docs/guide/collaboration#sharing-a-project). |
| Switching AI on for the workspace | The workspace's settings. See [The AI agent](/docs/guide/ai#turning-it-on). |
The app has no button to delete, archive or move a project. Individual notes can be trashed and deleted forever from the binder, but the project itself stays in its workspace and keeps counting towards the workspace's project limit.
## Customising the ribbon [#customising-the-ribbon]
The ribbon is yours, not the project's. Your arrangement is saved with your account, so it follows you to every project and every device, and your co-writers keep their own.
A project's ribbon starts with five views, chosen by how the project was started. See [Project types](/docs/reference/project-types#the-ribbon-a-project-starts-with). Every other view is under **More**.
| To | Do this |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Pin a view | Open **Customize** and tick it. Finishing a checklist step about a view also pins it. |
| Hide a view | Right-click it in the ribbon and choose **Remove from ribbon**, or untick it in Customize. It moves under **More**. |
| Reorder | Right-click a view and choose **Move up** or **Move down**, or use the arrows in Customize. |
| Show all | In Customize, tick **Show every view**. Pinning, hiding and reordering are switched off while it is on, and the ribbon scrolls if the views don't fit. |
| Start again | **Reset to default**, beside the Ribbon heading in Customize. |
A view that belongs to a module is only offered while that module is on.
If you are offline when you change the ribbon, it stays as you arranged it in that tab and is saved with your next change.
## The Customize dialog [#the-customize-dialog]
Open it from **More → Customize…** in the ribbon, by right-clicking a ribbon view, or with the command "Customize: ribbon, inspector and the look of the page". Each section has its own **Reset to default** once you have changed something.
| Section | What you can change |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ribbon** | As above. |
| **Inspector** | Which panels are shown and in what order: Properties, Outline, Links, Story, Comments, History, AI. Panels the project doesn't have are not offered. Tick **One tab for each panel, instead of Note and Review** to stop panels sharing tabs. With everything hidden, Links stays. |
| **The page** | How the text you write looks: see below. Printed and exported pages have their own formats. |
| **Project home** | Which blocks the [project home](/docs/guide#the-project-home) shows, and their order. |
| **Guidance** | **Suggest a way in when a note is empty**, and **Show "Getting started" in this project** where the project has a checklist. |
**Reset everything to how a new project starts**, at the bottom, clears all five.
### The page [#the-page]
| Setting | Choices (default first) |
| ---------------- | ---------------------------------- |
| **Typeface** | Serif, Sans-serif, Typewriter |
| **Text size** | Medium, Small, Large, Extra large |
| **Line width** | Normal, Narrow, Wide |
| **Line spacing** | Normal, Tight, Relaxed |
| **Paragraphs** | Space between, First line indented |
# Limits on the hosted version (/docs/guide/quotas)
No limit locks a feature, deletes what you wrote or stops you exporting it. Every view and module is on both plans; the limits are only on room: projects, storage and people.
The Free limits exist because storage, database space and email all cost money, and everyone on the Free plan shares what the project can afford. Pro raises them, at one price for the whole workspace. The plans are described in [Plans and billing](/docs/guide/plans).
## The limits [#the-limits]
| Limit | Free | Pro | Why |
| ----------------------------------------------------- | ----------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------- |
| Projects per workspace | 10 | Unlimited | Database space |
| Storage per workspace | 50 MB | 50 GB | File storage. Counts uploaded files and version snapshots |
| One uploaded file | 10 MB | 100 MB | File storage, and the memory a server function has |
| Workspace members | 3, counting the owner | 25 | The collaboration server and email |
| Guests per shared project | 5 | 200 | The same. A guest is someone a project is shared with who is not a workspace member |
| Hosted AI | None | 1,500 credits a month | The model bill |
| Automatic versions per note | The latest 40 | The latest 40 | File storage. Versions you name are kept |
| Invitations and shares | 40 invitations and 60 shares an hour per person | The same | Keeps the email service from being used for spam |
| Sign-in attempts, comments, saved versions, web clips | Rate limited per person | The same | Keeps one script from tying up the server |
## What has no limit [#what-has-no-limit]
* Views and modules. Every feature is on both plans.
* The length of your notes, and the number of notes in a project.
* Export.
## What happens when you reach one [#what-happens-when-you-reach-one]
* You get a message that says what the limit is.
* You can't add more of that thing until you free some room (delete a project you no longer need, or remove files and old versions) or the workspace [moves to Pro](/docs/guide/plans#upgrading).
* **Nothing is deleted, and nothing becomes read-only.** You can keep writing in the projects you have.
* **Export always works.** No limit ever stops you taking your work out.
If you keep reaching a limit, Pro is the fix that takes a minute: unlimited projects, 50 GB of storage, 25 members and 200 guests per project, for $10 a month for the whole workspace. See [when Pro is worth it](/docs/guide/plans#when-pro-is-worth-it).
The same holds for a workspace that goes from Pro back to Free while it is over the Free limits: it keeps everything, and only can't add more.
## The AI agent [#the-ai-agent]
On your own API key, or on a model on your own computer, there is no AI allowance to run out of: what a run costs is between you and your provider. That is the only way to run the agent on Free, and it works on Pro too.
A Pro workspace also has hosted AI, with 1,500 credits each billing period. One credit is 1,000 input tokens, and output tokens count five times. When the credits are used up, hosted runs stop until the period renews; runs on your own key carry on. See [Hosted AI and credits](/docs/guide/plans#hosted-ai-and-credits).
On both plans there is a rate limit per person, which protects the server and has nothing to do with money.
## What it costs to run [#what-it-costs-to-run]
What each service the hosted version runs on costs, and how Pro subscriptions and sponsorship pay for it, is in [the README](https://github.com/ItzSudhan/plotra#what-it-costs-to-run).
# Timeline and canvas (/docs/guide/timeline-and-canvas)
A timeline shows when things happen in the story. A canvas is a board where you place things wherever you like. Both are notes in the binder, so a project can have as many of each as it needs: one timeline for the war and one for the heist, a canvas per act.
Neither needs a module.
## Creating and opening [#creating-and-opening]
Create a timeline or a canvas like any other note: **New…** at the top of the binder, then **Timeline** or **Canvas**. "New timeline" and "New canvas" in the command palette do the same. Click the note in the binder to open it.
A timeline or a canvas cannot be changed into another kind of note, and a text note cannot be changed into one.
## Timeline [#timeline]
Story time runs left to right. Scenes sit where their **Story date** says, and last as long as their **Duration** says. Events that are not scenes, such as a war or a birth, are added straight to the timeline.
### What appears on a timeline [#what-appears-on-a-timeline]
| Item | Where it comes from | Look |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------- |
| A scene (or another dated note) | Any note with a **Story date** the timeline's calendar can read. Folders, canvases and timelines are skipped. | A bar with the note's icon |
| An event | Added on this timeline. It belongs to this timeline only. | A bar with a flag |
Every timeline in a project shows the same dated notes, because the dates are properties of the notes. Events are separate for each timeline.
Scenes with no story date are listed along the bottom as **Undated scenes**.
### Story dates and durations [#story-dates-and-durations]
A scene has two properties that place it, both in the **Properties** panel of the inspector:
* **Story date** is written `YYYY-MM-DD`, or `YYYY-MM-DD HH:mm` with a time. The month and day may be left off: `1820` is the first day of that year. A year can be negative, `-0450-02-01`, and up to six digits.
* **Duration** is written as a number and a unit: `2h`, `3 days`, `1h 30m`, `2 weeks`. The units are minutes, hours, days, weeks, months and years, in full or shortened.
With the Gregorian calendar a story date can also be written the way your browser understands, such as "3 May 1820". With a custom calendar it can be written with a month's name and two numbers, such as "4 Frostmonth 312".
A date the calendar cannot read leaves the scene among the undated ones.
To give another kind of note a place on the timeline, add a text property called "Story date" to that kind, and "Duration" if you want a length. See [custom fields](/docs/guide/vault-and-binder#custom-fields).
The World bible's **Event** type has a **Story date** field already, so those entries appear on the timeline too. They cannot be dragged: change the date in the entry's properties.
### Placing scenes [#placing-scenes]
There are four ways to put a scene on the timeline. Each one writes the scene's **Story date**, so the others follow.
1. Type a **Story date** in the scene's properties.
2. Drag the scene from the **Undated scenes** strip onto the timeline.
3. Drag a note from the binder onto the timeline.
4. Click a scene on the timeline and change the date in the panel that opens.
When you drop a note from the binder, a note whose kind has a **Story date** property is placed at that point. Any other note, or one you cannot edit, becomes a new event with the note's title, linked to the note. Dropping works in **Chronological** mode only.
### Moving and stretching [#moving-and-stretching]
* **Drag** a bar sideways to change when it starts. Its length stays the same.
* **Drag the right edge** to change how long it lasts. This writes the scene's **Duration**.
* **Click** a bar to select it and open its panel.
* **Double-click** a bar to open the scene, or the note an event is about, in a new tab.
Movement snaps to a round unit for the zoom you are at: a minute when zoomed right in, then 5 and 15 minutes, an hour, 6 hours, a day, a week, 30 days, a year.
You can move a scene if you can edit that scene, and an event if you can edit the timeline.
### The panel [#the-panel]
Clicking a bar opens a panel at the top right.
For a scene: its title (click to open it), **Story date**, **Duration**, and the date written out in full. Clearing the story date takes the scene off the timeline.
For an event:
| Field | What it is |
| ---------------- | ------------------------------------------------------------------------------------------------- |
| **Title** | Up to 80 characters. |
| **Starts** | A date in the timeline's calendar. |
| **Ends** | Optional. It must be after the start. |
| **Lane** | Shown when lanes are on. Which lane the event sits in. |
| **About** | A note the event is about, or **No linked note**. Double-clicking the event then opens that note. |
| **Notes** | Free text, up to 4,000 characters. |
| Colour dots | The event's colour. Click the chosen colour again for grey. |
| **Delete event** | Removes it at once. |
A date the calendar cannot read is outlined in red and not saved.
### Events [#events]
* Click **Event** in the toolbar to add one in the middle of what you can see.
* Double-click an empty part of the timeline to add one at that moment, in that lane.
A new event is called "New event". Events are for things that happen in the story but are not a scene you write. Deleting the note an event is about keeps the event and drops the link.
### Lanes [#lanes]
**Lanes** in the toolbar splits the timeline into rows.
| Lanes | A lane for each | A scene goes in |
| ----------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **No lanes** | — | One row for everything |
| **Plot threads** | Plot thread | Every thread it is in on the [plot grid](/docs/guide/planning-views#plot-grid). A scene in two threads appears in both lanes, in the thread's colour. |
| **POV character** | Character who is some scene's point of view | The lane of its **POV** property |
| **Location** | Location some scene is set in | The lane of its **Location** property |
Whatever has no lane goes in the last one: **No thread**, or **Unassigned**.
Dragging a scene up or down into another lane:
* In **POV character** or **Location** lanes, it changes the scene's **POV** or **Location**. Dropping it in **Unassigned** clears the property.
* In **Plot threads** lanes, scenes do not change lane by dragging. Put a scene in a thread on the plot grid.
An event can be dragged to any lane. An event remembers one lane, so after you switch from one kind of lanes to another it sits in **No thread** or **Unassigned** until you place it again.
Bars that overlap in time are stacked on separate rows inside their lane.
### Zoom and pan [#zoom-and-pan]
| Do this | And |
| ------------------------------------------- | ---------------------------------------- |
| `⌘` and scroll | Zoom in or out around the pointer |
| **Zoom out** and **Zoom in** in the toolbar | Zoom around the middle |
| **Fit everything** | Show the whole span of scenes and events |
| Drag an empty part of the timeline | Pan |
| Scroll sideways, or `⇧` and scroll | Pan |
The zoom runs from single minutes to hundreds of thousands of years on one screen. The axis labels change with it, from times of day to days, months and years.
A timeline with nothing on it opens on the thirty days around today in the Gregorian calendar, or around the first day of year 1 in a custom calendar.
### Chronological and narrative [#chronological-and-narrative]
The two buttons in the toolbar choose what the horizontal axis means.
* **Chronological** is story time. Everything above applies.
* **Narrative** lays the dated scenes out in reading order, one slot each, numbered, with each scene's date above it. A scene that happens earlier in story time than the one before it is marked **flashback**. Events are not shown. Nothing can be dragged, and **Event** is greyed out.
In **Chronological**, the **Show reading order** button draws a line from each scene to the next in reading order. It is on to begin with. A step backwards in time is drawn as a dashed orange line: a flashback. Point at a line to see which two scenes it joins.
### Calendars [#calendars]
A timeline uses the Gregorian calendar until you choose another. The **Calendar** list in the toolbar has every calendar in the project and **Manage calendars…**.
To make a calendar for an invented world:
1. Choose **Calendar**, then **Manage calendars…**.
2. Click **New calendar**. In a project with no calendars yet, the dialog opens straight on a new one.
3. Fill in the fields below. A line at the bottom shows how the date 312-02-05 reads in your calendar.
4. Click **Save calendar**. A new calendar is put on this timeline at once.
| Field | What it is | Limits |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| **Name** | The calendar's name. | 80 characters |
| **Hours per day** | The length of a day. Starts at 24. | 1 to 1,000 |
| **Months** | A name and a number of days for each. A new calendar starts with twelve months of 30 days. **+ Add month** adds one; the `×` removes one. | 1 to 60 months, each 1 to 1,000 days, names up to 40 characters |
| **Eras** | Optional. A name and the year the era starts in. Years are then counted from the era's first year: with an era "AE" starting in year 300, the year 312 reads "13 AE". | Up to 50 |
A month with no name, or an era with no name, is dropped when you save.
Things to know about calendars:
* Calendars belong to the project. Every timeline can use any of them, and each timeline remembers its own choice.
* A custom calendar has no leap years. Every year is the same length.
* Dates are still written as numbers: `312-04-17` is day 17 of the fourth month of year 312.
* In the Gregorian calendar, years before 1 are shown as BC.
* **Edit** and **Delete** in the dialog change or remove a calendar. Deleting is immediate. A timeline whose calendar was deleted goes back to Gregorian.
* Scene dates are text, so they are read again in whatever calendar the timeline uses. Events keep their place as a count of minutes, so their dates read differently after you switch calendar.
* Saving a project as a template copies its calendars.
* The [continuity checks](/docs/guide/canon#continuity-checks) read story dates too.
Creating, editing and deleting calendars needs edit access to the project. Choosing a timeline's calendar needs edit access to that timeline.
### What is saved, and for whom [#what-is-saved-and-for-whom]
The calendar, the lanes, chronological or narrative, and the reading-order line are saved on the timeline, so everyone sees it the same way. If you cannot edit the timeline you can still change lanes and mode for yourself; that is not saved. The zoom and position are not saved.
### Under a spoiler horizon [#under-a-spoiler-horizon]
When a [spoiler horizon](/docs/guide/canon#the-spoiler-horizon) is on, the timeline shows only the scenes the audience knows by then.
## Canvas [#canvas]
An endless board for arranging things by hand: a storyboard, a mind map, a wall of index cards with string between them. Everyone who has the canvas open works on it together, and you see their pointers with their names.
### The toolbar [#the-toolbar]
The buttons at the top left:
| Button | What it adds |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Add a note card** | Opens a search box. Type part of a title and click a note, or press `↵` for the first match. Folders and canvases are not offered. |
| **Add a text card** | A plain card to write on. |
| **Add an image or shot panel** | A picture with a caption and shot details. |
| **Add a group** | A labelled frame that holds other cards. |
| **Fit everything** | Zooms to show the whole canvas. |
A new card appears in the middle of what you can see. You can also drag any note from the binder onto the canvas to make a note card where you drop it.
### Kinds of card [#kinds-of-card]
**Note card.** A live window onto a note in the binder: its kind, status dot, title and the first lines of its synopsis. Change the note and the card changes. Double-click to open the note in a new tab. If the note is in the trash the card reads "In the trash". If it was deleted, or you are not allowed to see it, the card reads "Restricted or deleted note" and does not show its title.
**Text card.** Double-click to write, click away to save. Up to 5,000 characters. A colour tints the whole card.
**Image / shot panel.** Select it and fill in the panel at the top right:
| Field | What it is |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Image URL** | The address of a picture on the web, starting with `http://` or `https://`. Pictures are not uploaded to the canvas. |
| **Caption / action** | Text under the picture, up to 500 characters. |
| **Shot…** | Extreme wide, Wide, Full, Medium, Medium close-up, Close-up, Extreme close-up, Over the shoulder, POV or Insert. |
| **Camera…** | Static, Pan, Tilt, Dolly, Truck, Crane, Handheld, Zoom or Tracking. |
| **Duration (seconds)** | How long the shot lasts. |
The shot, camera move and duration show as small badges on the picture.
**Group.** A dashed frame with a label, for an act or a sequence. Select it to change the label (up to 120 characters) and the colour. Drag a card onto a group to put it inside; it then moves with the group. Drag it out to take it out. Removing a group leaves its cards where they were.
### Working with cards [#working-with-cards]
| To do this | Do this |
| ----------------- | ---------------------------------------------------------------------------------------- |
| Move a card | Drag it. |
| Resize a card | Select it and drag a corner or an edge. |
| Change its colour | Select it and click a colour dot in the panel. Click the same colour again to remove it. |
| Remove a card | Select it and press `⌫` or `Delete`, or click **Remove from canvas** in the panel. |
| Select several | Hold `⇧` and drag a box, or `⌘`-click cards. |
Removing a note card takes it off the canvas only. The note itself is untouched.
### Connections [#connections]
Drag from one of the four dots on a card's edges to another card to draw an arrow between them. Groups have no dots and cannot be connected.
Click an arrow to select it. The panel at the top right then has a **Label** field (up to 80 characters), for a word such as "causes", "then" or "meanwhile", and **Remove**. `⌫` also removes a selected arrow. Removing a card removes its arrows.
### Getting around [#getting-around]
Drag the background to pan and scroll to zoom. The buttons at the bottom left zoom in, zoom out and fit. The small map at the bottom right shows the whole canvas; drag in it to move.
### What a canvas feeds [#what-a-canvas-feeds]
* A note card counts as a link from the canvas to that note. The canvas shows up in the note's [backlinks](/docs/guide/links#backlinks) and in the [graph](/docs/guide/world-views#graph).
* The text of text cards and captions is searchable, and a `#tag` written there is a tag on the canvas.
* That text gives the canvas a word count in the binder. It is not counted in your [writing stats](/docs/guide/writing-goals#what-is-counted).
* A canvas has version history like a text note. A version shows how many cards and connections it had; restore it to see it.
### Who can edit [#who-can-edit]
If you cannot edit the canvas, the toolbar reads **Read only**. You can still pan, zoom and open notes from their cards.
A canvas is saved the same way as a text note, including while you are offline. See [Saving and working offline](/docs/guide/editor#saving-and-working-offline). If two people change the same card at the same moment, the later change wins for that card; changes to different cards are both kept.
The Canvas view shows everything, whatever the spoiler horizon is.
# The vault and the binder (/docs/guide/vault-and-binder)
Everything your story needs lives in one project, so nothing is left in a file you can't find. A project is a **vault**: a set of notes that link to each other. The **binder** is the tree on the left that holds them.
This page covers the binder and the frame around it: tabs and panes, the inspector, the status bar, the command palette and the quick switcher. The page you write on has its own: [The editor](/docs/guide/editor).
## Kinds of note [#kinds-of-note]
Everything in the binder is a note of some kind. The kind decides its icon, its template and which view opens it.
| Kind | For | Opens in |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- |
| Folder | Grouping. A folder can also stand for a book, an act or a season. | The editor (a folder has a page of its own) |
| Chapter | A group of scenes. | The editor |
| Scene | The text of the story. | The editor |
| Note | Anything else you want to write down. | The editor |
| Character, Location | The people and places of the story. They start with a sheet of headings to fill in. | The editor |
| World entry | A page of a type you define: a faction, an object, a magic system. In menus it goes by the name of its type. See [Canon](/docs/guide/canon#the-world-bible). | The editor |
| Research | A source or a clipped page. It starts with "Summary" and "Notes" headings. | The editor |
| Canvas | A storyboard. | The canvas |
| Timeline | A timeline. | The timeline |
| Dialogue | A branching conversation. Only with the **Interactive narrative** module on. | The dialogue view |
Any note can hold other notes, not only folders and chapters. Folders and chapters are the two the binder shows as containers, and the two a new note goes inside when one of them is selected.
A project can use its own words for the kinds: "Session" or "Sequence" for a chapter, say. The binder, the menus and the commands then use those words. See [Project settings](/docs/guide/project-settings).
### Changing a note's kind [#changing-a-notes-kind]
Right-click the note and choose **Change kind**, or use the **Kind** field at the top of the **Properties** panel.
* Folders, chapters, scenes, notes, characters, locations and research notes can be turned into one another. With the **World bible** module on, the list also has your entity types.
* A canvas, a timeline or a dialogue can't change kind, and a text note can't become one.
* The text stays as it is. The properties shown become those of the new kind; the values of the old kind's fields are kept and come back if you change the kind back.
## Working in the binder [#working-in-the-binder]
### Creating [#creating]
The buttons at the top of the binder:
| Button | What it does |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **New note** (`⌘⌥N`) | Adds a note. |
| **New folder** (`⌘⌥⇧N`) | Adds a folder. |
| **New…** | A menu of every kind: Note, Scene, Chapter, Folder, Character, Location, Research, Canvas and Timeline, Dialogue when its module is on, and one entry for each of your entity types when **World bible** is on. Below them: **Beat sheet…**, **Import…** and **Export project…**. |
| **Collapse all** | Closes every folder in the tree. |
| **Share project…** | Opens the share dialog. Only for people who manage the project. See [Working together](/docs/guide/collaboration#sharing-a-project). |
Where a new note lands:
1. Inside the selected folder or chapter, at the end.
2. Otherwise beside the selected note, or the note you have open, in the same folder.
3. Otherwise at the end of the top level.
To choose the place yourself, right-click any note and use **New inside**.
A new note is called "Untitled" and its kind ("Untitled scene"), opens in a new tab, and its name is ready to be typed over in the binder. A new scene is written in the project's format: prose, or the script format of a screenplay project.
There is also a command for each kind in the command palette ("New scene", "New character"), and the quick switcher creates a note from a name that doesn't exist yet.
In an empty project the binder offers two links instead of a tree: **Write a scene** and **start a chapter**.
### Opening [#opening]
| Do this | And the note opens |
| -------------------------- | ------------------------------------------------------------------------ |
| Click | In the current tab, replacing what was there (unless that tab is pinned) |
| `⌘`-click, or middle-click | In a new tab |
| `⌘⌥`-click | In a new pane to the right |
Clicking a folder opens and closes it in the tree. `⌘`-click a folder to open its own page.
### Keys [#keys]
Click in the binder, then:
| Keys | What it does |
| --------------- | ----------------------------------------------------------------------------------------- |
| `↑` `↓` | Move the selection |
| `→` | Open a folder; once open, go to its first note |
| `←` | Close a folder; once closed, go to its parent |
| `↵` | Open the note (with `⌘` in a new tab, with `⌘⌥` to the right), or open and close a folder |
| `F2` | Rename |
| `⌫` or `Delete` | Move to the trash, without asking |
### Moving [#moving]
Drag a note in the binder. A line shows where it will go if you drop it above or below another note, and the row is outlined if you drop it inside.
* Drop on the top or bottom edge of a row to put the note **before** or **after** it.
* Drop on the middle of a row to put it **inside**, at the end. This works on any note, not only folders. The row opens to show it.
* Drop on the empty space under the tree to move it to the end of the top level.
* A note can't be dropped into itself or into something inside it.
A move takes everything inside the note with it. You can also drag a note from the binder onto a canvas or a timeline; see [Timeline and canvas](/docs/guide/timeline-and-canvas).
### The context menu [#the-context-menu]
Right-click a note. Which items are there depends on the note.
| Item | What it does |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Open in new tab** | Not for folders. |
| **Open to the right** | Opens the note in a new pane beside the current one. Not for folders. |
| **Local graph** | Opens the graph around this note, to the right. Not for folders. See [The graph](/docs/guide/links#the-graph). |
| **Plot grid**, **Corkboard**, **Manuscript**, **Read** | Opens that view on this note and what is inside it. Shown for folders, chapters and any note that has notes inside. With their modules on, **Production**, **Translate** and **Publish** are here too. See [Planning views](/docs/guide/planning-views). |
| **New inside** | A submenu of kinds. The new note goes inside this one, at the end. |
| **Rename** (`F2`) | Edits the name in place. `Enter` or clicking away keeps it, `Esc` cancels. A name can be 200 characters. |
| **Duplicate** | Copies the note. See below. |
| **Change kind** | See [Changing a note's kind](#changing-a-notes-kind). |
| **Status** | Sets the note's status to one of the project's stages. |
| **Import…** | Imports files into this folder or chapter. See [Import and export](/docs/guide/import-export). |
| **Export…** | Exports this note and what is inside it. |
| **Move to trash** (`⌫`) | See [The trash](#the-trash). |
**New inside**, **Rename**, **Change kind**, **Status** and **Import…** are greyed out if you can't edit. **Move to trash** is greyed out if you can't delete. See [Roles and permissions](/docs/reference/roles-and-permissions).
### Duplicating [#duplicating]
**Duplicate** makes a copy called "*name* copy" directly below the original, with its name ready to be changed. The copy has the same text, kind, status, synopsis, tags, aliases, properties and canon settings, and so does a copy of every note inside it. Notes in the trash are left out. Comments and version history belong to the original and are not copied.
### The trash [#the-trash]
**Move to trash** takes a note, and everything inside it, out of the binder and closes its tabs. Nothing is deleted yet. Links to a trashed note are struck through, and the note is left out of the views and the word count.
The **Trash** is at the bottom of the binder, with a count. Open it to see what is there, newest first. Point at a row for its two buttons:
| Button | What it does |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Restore** | Puts the note back where it was, with everything inside it. If the folder it was in is itself still in the trash, the note comes back at the end of the top level. |
| **Delete forever** | Asks first, then deletes the note and everything inside it. This can't be undone. |
**Empty trash** deletes everything in it, after asking. It is for people who may delete in the whole project; anything you aren't allowed to delete stays, and a message says how many items stayed.
A note has to be in the trash before it can be deleted forever. A note that a review stage has locked, or a folder with a locked note inside, can't be trashed by anyone but its approvers; see [Review and editorial](/docs/modules/editorial).
### What a row shows [#what-a-row-shows]
| Mark | Meaning |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| A coloured dot at the right | The note's status. Notes in the first stage (Draft, to begin with) show none. |
| A small coloured square | The note's colour label, set under **Label** in the Properties panel. Point at it for the label's name. |
| A closed eye, and the row dimmed | Under a [spoiler horizon](/docs/guide/canon#the-spoiler-horizon), the audience hasn't been told about this note yet. |
| Bold name | The note open in the active tab. |
Which folders are open is remembered per project in your browser. Drag the edge of the binder to make it wider or narrower; the inspector has the same edge.
## Tabs and panes [#tabs-and-panes]
Notes and views open as tabs in the middle of the screen.
| Keys | What it does |
| ------------- | --------------------------------------- |
| `⌘⌥\` | Split the pane to the right |
| `⌘⌥→` / `⌘⌥←` | Next and previous tab |
| `⌥W` | Close the tab |
| `⌘⇧M` | Make the pane fill the window, and back |
The command palette has three more that have no keys to begin with: **Split down**, **Pin or unpin tab** and **Close all tabs**.
* **Splitting** moves the active tab into a new pane, so the pane needs at least two tabs.
* Drag a tab to another pane, or to the edge of one to make a new split.
* Middle-click a tab to close it.
* **A pinned tab** stays open: opening another note from the binder goes beside it instead of replacing it. It shows a pin where the close button was. Unpin it, or use `⌥W`, to close it.
* Coloured dots on a tab are the other people who have that note open. A single dot in place of the close button means the note has changes that haven't reached the server yet; see [Saving and working offline](/docs/guide/editor#saving-and-working-offline).
With no tab open, the middle of the screen is the **project home**: the notes you last worked on, this session's words against your goal, the next step of the getting-started checklist, and a few shortcuts. Choose which of these it shows under **Customize**.
On a phone-sized screen there is one pane at a time; the splits come back when there is room. The binder and the inspector open over the page as drawers, and the ribbon becomes a bar across the top.
### Saved layouts [#saved-layouts]
Your open tabs and splits are remembered per project in your browser, along with which tabs are pinned. To keep more than one arrangement, for example "Drafting" and "Plotting", save it as a **layout**.
1. Press `⌘⇧L`, or choose **Saved layouts** under **More** in the ribbon.
2. Type a name and press `Enter` to save the current arrangement. Typing the name of a layout you already have replaces it.
3. To switch, open the list again and pick one. The bin icon on a row deletes it.
Saved layouts are stored with your account, per project, so they follow you to another computer and nobody else sees them. A name can be 60 characters. When a layout is opened, tabs for notes that have since been trashed or deleted are left out.
## The inspector [#the-inspector]
The inspector is the sidebar on the right. It is about the note in the active tab. Show or hide it with `⌘⇧\`.
| Tab | Panels | What is in it |
| ---------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Note** | **Properties**, **Outline** | The note's fields, and its headings. Click a heading in the outline to jump to it. |
| **Links** | | Backlinks, outgoing links and unlinked mentions. `⌘⇧B` opens it. See [Backlinks](/docs/guide/links#backlinks). |
| **Story** | | Canon status and reveals. Only when **World bible**, **Releases & reveals** or **Research & sources** is on. See [Canon](/docs/guide/canon#canon-status). |
| **Review** | **Comments**, **History** | Comment threads and suggestions, and saved versions. See [Working together](/docs/guide/collaboration#comments). |
| **AI** | | The AI chat. Only where AI is on. See [AI](/docs/guide/ai). |
The gear at the right of the tabs opens **Customize**, where you can give each panel a tab of its own, hide panels and change their order.
### The Properties panel [#the-properties-panel]
From top to bottom:
| Field | What it is |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Kind** | The note's kind. See [Changing a note's kind](#changing-a-notes-kind). |
| **Status** | A stage of the project's workflow. |
| **Label** | One of the project's colour labels, or **None**. The field is there once the project has labels; they are defined in [Project settings](/docs/guide/project-settings) and are the same for everyone in the project. The label shows as a small coloured square on the note's row in the binder. |
| **Synopsis** | What happens here, in a line or two. Saved when you click away. Up to 2,000 characters. |
| **Properties** | The fields of this kind of note. See [Properties](#properties). |
| **Tags** | See [Tags](#tags). |
| **Aliases** | Other names the note goes by, for links and mentions. |
| **Words**, **Characters**, **Reading time**, **Updated** | Counts for the note, a reading time at 230 words a minute, and when it last changed. |
With the **Review & editorial** module on, the panel also has the note's review controls.
Without edit access the fields can be read but not changed.
## Properties [#properties]
Every note has properties: fields about it, shown in the inspector under **Properties**.
* Every note has a status (Draft, Revised, Final to begin with), a synopsis, tags and aliases. Aliases are other names the note goes by.
* Each kind has its own fields. A scene has a point of view, a location, a story date, a duration and plot threads. A character has a role, an age, an arc, a first appearance, and dates of birth and death. A location has a type and a region. A chapter has a target word count. A research note has the fields of a reference: type, authors, publisher, year, URL and so on.
* You can add your own fields per kind.
Properties are what the other views are built from. The outline shows them as columns. The timeline places scenes by their story date. The corkboard shows each synopsis.
### Custom fields [#custom-fields]
The fields belong to the kind, not to one note: add "Mood" to one scene and every scene in the project has it.
1. Open a note of the kind and go to **Properties** in the inspector.
2. Click **Add property to scenes** (the button names the kind).
3. Give it a name, up to 60 characters, choose a type, and click **Add**.
| Type | Holds |
| ---------------- | ----------------------------------------------------------------------------------------------------------- |
| **Text** | A line of text. |
| **Number** | A number. |
| **Date** | A calendar date. |
| **Select** | One choice from a list. |
| **Multi-select** | Several choices. Type a new one and press `Enter` or a comma; it joins the list for every note of the kind. |
| **Link to note** | Another note. The link shows in backlinks and in the graph. |
| **Checkbox** | Yes or no. |
| **URL** | A web address, with a button to open it. |
Point at a field's name for its menu: **Rename**, **Move up**, **Move down** and **Remove from template**. Removing a field hides it on every note of the kind; the values are kept and return if you add a field with the same name again.
Adding and changing fields needs edit access to the project. For an entity type, the fields are the type's own; they can also be edited where the type is defined, see [Canon](/docs/guide/canon#the-world-bible).
The inspector has no place to type the choices of a new **Select** field. Use **Multi-select**, which takes new choices as you type them. Entity types are the exception: their choices are set where the type is defined.
## Tags [#tags]
Tag a note to group it across folders. Tags can be nested with a slash, like `subplot/romance`.
There are two ways to tag a note:
* In the inspector, under **Tags**: type a tag and press `Enter` or a comma.
* In the text: write `#subplot` anywhere. See [Tags in the text](/docs/guide/editor#tags-in-the-text).
A tag is stored in lower case, with spaces turned into hyphens. A note can have 50 tags.
The **Tags** tab at the top of the left sidebar, beside **Binder**, lists every tag in the project with the number of notes that carry it. Nested tags are shown as a tree, and a parent counts the notes of its children. Click a tag to list its notes underneath; click a note to open it, `⌘`-click for a new tab. The command "Show tags" opens the pane.
## The editor [#the-editor]
Notes open in the editor. In short:
* `/` opens the block menu: headings, lists, tables, callouts, images and dividers.
* Markdown-style shortcuts work as you type: `#` and a space for a heading, `-` for a list, `>` for a quote.
* Selecting text shows a toolbar for bold, italic, links and comments.
* Blocks can be dragged by the handle on their left.
* **Focus mode** (`⌘⇧F`) hides everything but the text. **Typewriter scrolling** (`⌘⇧T`) keeps the line you are writing in the middle of the screen.
All of it, with tables, images, block tags, word counts and working offline, is on [The editor](/docs/guide/editor).
## Starting from a structure [#starting-from-a-structure]
A **beat sheet** lays out a known story structure as notes you can fill in. Choose **Beat sheet…** in the binder's **New…** menu, or run "New beat sheet (Save the Cat, Hero's Journey…)" from the command palette.
| Beat sheet | What it is |
| ----------------------- | -------------------------------------------------------------------- |
| **Save the Cat** | Blake Snyder's 15 beats, from opening image to final image. |
| **Hero's Journey** | Vogler's 12 stages of the monomyth. |
| **Three-act structure** | Setup, confrontation and resolution with the classic turning points. |
The dialog shows the acts and beats of the one you pick, with roughly how far into the story each beat falls. **Add** builds a folder named after the beat sheet, with a chapter for each act and a scene for each beat. Each scene's synopsis says what the beat does, so the corkboard, the outline and the plot grid show the structure straight away. The folder goes inside the selected folder or chapter if you can edit it, and otherwise at the end of the top level. The first beat opens in a tab.
The result is ordinary notes: rename them, reorder them, delete the ones you don't need.
To start a whole project from the shape of another, with its folders, kinds and fields but none of its writing, use a project template; see [Project settings](/docs/guide/project-settings).
## Finding things [#finding-things]
### The command palette [#the-command-palette]
`⌘P` opens the command palette: every command in the project, grouped, with its shortcut. Type to filter, `↑` `↓` to move, `↵` to run, `Esc` to close. Commands that belong to a module are only listed while it is on. The full list is on [Keyboard shortcuts](/docs/reference/keyboard-shortcuts).
### The quick switcher [#the-quick-switcher]
`⌘O` opens the quick switcher. Type part of a note's name, or of a folder it is in.
| Keys | What it does |
| ----- | -------------------------------- |
| `↵` | Open the note in the current tab |
| `⌘↵` | Open it in a new tab |
| `⌘⌥↵` | Open it to the right |
If nothing has exactly the name you typed, the last row offers to **Create** a note with it. Folders are not listed.
`⌘⇧O` searches the text of every note instead of the names.
## The ribbon [#the-ribbon]
The ribbon is the strip of buttons at the far left.
* At the top: back to the workspace, **Toggle binder** (`⌘\`), **Quick switcher** and **Command palette**.
* In the middle: a few views, each with its name. Which ones a project starts with depends on what it is for.
* **More**: every other view, grouped; the tool sets this project hasn't switched on, for people who manage it; **Saved layouts**, **Focus mode**, **Typewriter scrolling**, **Keyboard shortcuts** and **Customize…**.
* At the bottom: **Project settings** and **Toggle inspector** (`⌘⇧\`).
Right-click a view in the ribbon for **Move up**, **Move down**, **Remove from ribbon** and **Customize…**.
### Customize [#customize]
**Customize** is where you set up the frame for yourself. Nothing here changes anyone else's screen, and it follows you to every project and device.
| Section | What you can change |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Ribbon** | Which views are in the ribbon and in what order, or **Show every view**. |
| **Inspector** | Which panels are shown, their order, and **One tab for each panel, instead of Note and Review**. |
| **The page** | Typeface, text size, line width, line spacing and paragraphs. See [How the page looks](/docs/guide/editor#how-the-page-looks). |
| **Project home** | Which blocks the project home shows, and their order. |
| **Guidance** | **Suggest a way in when a note is empty**, and whether the getting-started checklist shows in this project. |
Each section has **Reset to default** once you have changed it, and **Reset everything to how a new project starts** is at the bottom.
## The status bar [#the-status-bar]
The bar along the bottom of the window, from left to right:
| Item | What it is |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| Workspace / project | Where you are. |
| **World as of …** | Shown while a spoiler horizon is on. Click the name to open the release roadmap, or the cross to show the whole world. |
| **words in project** | Every note outside the trash, as last saved. |
| **words** · **chars** | The note in the active tab. |
| **this session** | Words typed this sitting, against your session goal. Click for stats and goals. |
| **Synced**, **Connecting…** or **Offline** | Whether your changes have reached the server. |
| Avatars | The other people in the project right now. Point at one to see which note they are in; click to open it. |
| The bell | Your notifications. See [Notifications](/docs/guide/notifications). |
| Your avatar | The user menu. |
The counts and the sync states are explained on [The editor](/docs/guide/editor#word-counts).
### The user menu [#the-user-menu]
Click your avatar at the right of the status bar.
| Item | What it does |
| ---------------------- | ------------------------------------------------------------------------- |
| **Theme** | Light, Dark or System. |
| **Your settings** | Opens your account settings. See [Your account](/docs/guide/account). |
| **Keyboard shortcuts** | Opens the shortcuts list (`⌘/`). |
| **Getting started** | Brings back the checklist, if you closed it. |
| **Sponsor Plotra** | Opens the project's sponsorship page. Sponsoring buys nothing in the app. |
| **Sign out** | |
## Things to know [#things-to-know]
* **Limits.** A name can be 200 characters, a synopsis 2,000. A note can have 50 tags and 50 aliases.
* **Who can do what.** Viewers and commenters can open everything and change nothing in the binder. Editors and workspace members can create, move, rename, trash and delete. Sharing the project is for workspace owners and admins. See [Roles and permissions](/docs/reference/roles-and-permissions).
* **Other people's changes** to the binder show up in yours within a moment, without reloading.
* **Offline**, the binder can't be changed: a new note, a rename or a move is undone with a message if it can't reach the server. The text of notes you have opened before can still be edited; see [Saving and working offline](/docs/guide/editor#saving-and-working-offline).
* **Kept in your browser, not your account:** which folders are open, the widths of the sidebars, the open tabs and splits, pinned tabs, and changed keyboard shortcuts. Saved layouts, the ribbon, the inspector's tabs and the look of the page are kept with your account.
# Views (/docs/guide/views)
When the prose stops telling you what is wrong, look at the story another way. A view is a way of looking at your project. Views open as tabs, so you can put a timeline next to the scene you are writing. They all read the same notes: change something in one and the others follow.
There are three ways to open a view:
* **The ribbon** on the left. It starts with the five views your kind of project uses most. Every other view is under **More**, grouped as Plan, World, Read and publish, Team and progress, and Tools. You choose which ones stay in the ribbon.
* **The command palette** (`⌘P`). Each view has a command in the **Views** group; the names are in the tables below.
* **The binder.** Right-click a folder or a chapter to open it in a view that works on a folder. A timeline, a canvas or a dialogue tree opens when you click it, like any note.
## Views that are always there [#views-that-are-always-there]
| View | What it shows | Good for | Command |
| ----------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------- |
| **Editor** | One note. | Writing. See [The editor](/docs/guide/editor). | Click a note |
| **Graph** | Notes as dots, links as lines, for the whole project or around one note. | Seeing what connects to what, and what connects to nothing. | "Open graph view" (`⌘G`) |
| **Codex** | Characters, places and other world pages, grouped by type, like a wiki. | Looking things up. | "Open codex" (`⌘⇧C`) |
| **Relationships** | Characters, with labelled lines between them: ally, rival, parent. | Keeping who-is-what-to-whom straight. | "Open relationship map" (`⌘⇧R`) |
| **Outline** | A table of every note with its properties as columns. Edit in place, sort and filter. | Checking status, point of view and word counts across a book. | "Open outline" |
| **Corkboard** | A folder's scenes as index cards with title and synopsis. | Reordering. Drag a card and the binder order changes with it. | "Open corkboard of current folder" |
| **Plot grid** | Scenes down the side, plot threads across the top. | Seeing which thread goes quiet for too long. | "Open plot grid" |
| **Manuscript** | A folder's scenes stitched into one long, editable page. | Reading and revising across scene breaks. | "Open manuscript (Scrivenings) of current folder" |
| **Read** | A paginated, print-style preview of a folder. | Proofreading, and printing to PDF through your browser. | "Read / print preview of current folder" |
| **Activity** | What changed in the project, and who changed it. | Catching up. See [Notifications](/docs/guide/notifications). | "Open activity feed" |
| **Stats** | Words per day, the streak, and progress towards your goals. | Keeping the draft moving. See [Writing goals](/docs/guide/writing-goals). | "Open writing stats and goals" |
The details are on their own pages:
### Views that work on a folder [#views-that-work-on-a-folder]
Corkboard, Plot grid, Manuscript and Read work on a folder or a chapter. So do Production, Translate and Publish when their modules are on. There are two ways to say which folder:
* Right-click a folder or a chapter in the binder and choose the view. A note of any other kind offers the same views once it has notes inside it.
* Open the view from the ribbon or the command palette. It opens on the folder or chapter you have selected or open. If the note you have open has nothing inside it, the view opens on the folder that holds it. With nothing selected, it covers the whole project.
## Views that are notes [#views-that-are-notes]
A **timeline** and a **canvas** are notes in the binder. Create one like any other note and click it to open it. A project can have several of each. "New timeline" in the command palette creates a timeline. Both are covered in full in [Timeline and canvas](/docs/guide/timeline-and-canvas).
### Timeline [#timeline]
Story time on a horizontal axis. Scenes sit where their **Story date** property says and last as long as their **Duration**; drag a scene and the properties change. You can add events that are not scenes, split the timeline into lanes by plot thread, point of view or location, zoom from minutes to centuries, switch between story order and reading order with flashbacks marked, and use a calendar of your own invention.
Everything is in [Timeline and canvas](/docs/guide/timeline-and-canvas#timeline).
### Canvas (storyboard) [#canvas-storyboard]
An endless board for arranging things by hand: cards that show real notes, plain text cards, image and shot panels, groups, and labelled arrows between them. Several people can work on one canvas at once. A note placed on a canvas counts as a link to it.
Everything is in [Timeline and canvas](/docs/guide/timeline-and-canvas#canvas).
### Dialogue [#dialogue]
A **dialogue** note is a branching conversation. It can be created only while the Interactive narrative module is on. See [Interactive narrative](/docs/modules/interactive).
## Views that come with a module [#views-that-come-with-a-module]
A project's **modules** switch groups of tools on and off, so a novelist doesn't see game tools. The project type picks the starting set. Change it in [Project settings](/docs/guide/project-settings). A view whose module is off is not in the ribbon, under **More**, or in the command palette.
| Module | Views it adds | Where it is covered |
| --------------------- | --------------------------------- | --------------------------------------------------- |
| World bible | Continuity | [Canon](/docs/guide/canon#continuity-checks) |
| Releases & reveals | Release roadmap, Secrets & setups | [Canon](/docs/guide/canon#the-release-roadmap-view) |
| Research & sources | Sources | [Research](/docs/modules/research) |
| Review & editorial | Reviews | [Editorial](/docs/modules/editorial) |
| Production | Production | [Production](/docs/modules/production) |
| Interactive narrative | Dialogue, Quests, Strings | [Interactive narrative](/docs/modules/interactive) |
| Localization | Translate | [Localization](/docs/modules/localization) |
| Publishing | Publish | [Publishing](/docs/modules/publishing) |
| AI agent | AI | [AI](/docs/guide/ai) |
The commands are "Open release roadmap", "Open secrets & setups", "Open continuity", "Open sources", "Open reviews", "Open production", "Open quest designer", "Open strings (short-text fields)", "Open translate", "Open publish" and "Open AI chat". The AI view is offered only while AI is on for the workspace, the project and you.
## Views and the spoiler horizon [#views-and-the-spoiler-horizon]
When a [spoiler horizon](/docs/guide/canon#the-spoiler-horizon) is on, the Outline, Graph, Codex, Timeline, Read and Quests views leave out what the audience has not been told yet. The Codex filters this project's pages, not those of a shared world. The Corkboard, Plot grid, Manuscript, Relationships and Canvas views show everything regardless, and so do search and the quick switcher. The full list is in [What it hides](/docs/guide/canon#what-it-hides).
## Where a view keeps its settings [#where-a-view-keeps-its-settings]
Some things are stored in your browser and not with the project: the positions on the relationship map, the property columns you chose in the outline, which continuity warnings you dismissed, the spoiler horizon, your writing session's word count, and the pane layout you didn't save as a named layout. They won't follow you to another computer, and your co-writers don't see them.
A timeline's calendar, lanes, mode and reading-order line are stored on the timeline itself, so everyone sees the same. A canvas is a shared document: every card and connection is the same for everyone. Plot threads and relationships belong to the project. Filters in the graph, the outline and the codex are not kept at all; they reset when you close the tab, and so do the graph's positions and a timeline's zoom.
# World views (/docs/guide/world-views)
Three views show the world of the story instead of its order. The Graph draws every note and the links between them. The Codex lets you read your characters, places and other world pages like a wiki. The Relationships map shows who is what to whom.
All three are always available; none needs a module. The World bible module adds more to the Codex.
Three more views about the world belong to [Canon](/docs/guide/canon): the **Release roadmap** and **Secrets & setups** (with the Releases & reveals module) and **Continuity** (with the World bible module). See [The Release roadmap view](/docs/guide/canon#the-release-roadmap-view), [Who knows what](/docs/guide/canon#who-knows-what) and [Continuity checks](/docs/guide/canon#continuity-checks).
## Graph [#graph]
Every note is a dot and every link is a line. Use it to see what the story hangs on, and which notes nothing points at.
### Opening it [#opening-it]
| To open | Do this |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| The whole project | **Graph** in the ribbon, "Open graph view" in the command palette, or `⌘G` |
| The graph around one note | Right-click the note in the binder and choose **Local graph**, or run "Open local graph of current note". It opens to the right of what you have open. |
### What is drawn [#what-is-drawn]
* **A dot** is a note. Its colour is its kind. It grows with the number of links it has and, a little, with its word count.
* **A line** joins two notes that are linked, in either direction. Two notes get one line however many links there are between them.
There are three kinds of link, drawn at three weights:
| Link | Comes from | Drawn |
| ------------- | --------------------------------------------------------------------------- | --------------------- |
| Embed | A note embedded in another | Thickest |
| Link | A `[[link]]` in the text, or a note card on a canvas | Medium |
| Property link | A property that points at a note, such as a scene's **POV** or **Location** | Thinnest and faintest |
Labels appear as you zoom in. Bigger dots get theirs first.
The links are read again every 15 seconds while the view is visible, and whenever the binder changes. A link you have just typed takes a few seconds to appear, because links are indexed when the note is saved.
### Global and local [#global-and-local]
**Global** shows the whole project. **Local** shows one note and what is around it.
In **Local**, **Depth** sets how far to go: 1 shows the notes linked to the centre, 2 adds their links, 3 goes one step further. The centre note always shows its label.
A local graph opened for a note from the binder or the command palette stays on that note. If you switch a global graph to **Local**, it follows the note you last opened, and changes as you move from note to note.
### Search [#search]
Type in **Search graph** to light up the notes whose title or aliases contain the text. The rest are dimmed and the number of matches is shown in the box. `Esc` clears it.
### Filters [#filters]
| Control | What it does |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tag list | **All tags**, or one tag. Only notes with that tag are drawn. Tags set in the properties and tags written in the text both count. |
| **Orphans** | On: notes with no links are drawn. Off: they are hidden. It starts on. |
| **Property links** | On: property links are drawn and counted. Off: only links and embeds. It starts on. |
| The row of kinds at the bottom | Each kind with its colour and how many notes of it the project has. Click a kind to hide it, and again to show it. A hidden kind is struck through. |
Folders and timelines are hidden to begin with. In a local graph, the centre note is drawn whatever the filters say.
To find notes nothing links to, leave **Orphans** on and look at the dots with no lines. To see only the story's people and places, hide every kind but Character and Location.
Filters are not saved. They reset when you close the tab.
### Colours [#colours]
Colour always means kind. Characters, locations, scenes, chapters, research notes and plain notes each have their own colour; world entries share one; folders, canvases, timelines and dialogue trees are grey. The row at the bottom is the key. The colours follow your light or dark theme.
### Moving around [#moving-around]
| Do this | And |
| -------------------------------- | ---------------------------------------------------- |
| Point at a dot | It and its neighbours stay lit; everything else dims |
| Click a dot | Open the note. `⌘`-click opens it in a new tab |
| Scroll | Zoom |
| Drag the background | Pan |
| **Fit graph** (bottom right) | Bring the whole graph back into view |
| **Re-run layout** (bottom right) | Let the dots settle again |
The layout arranges itself for a couple of seconds whenever notes or links are added, then holds still. Positions are not saved; the graph is laid out afresh each time you open it.
### Empty states [#empty-states]
| You see | It means |
| ------------------------------------------------------------- | --------------------------------------------------------------------------- |
| "Nothing here yet. Create a note to start your graph." | The project has no notes. A **New note** button is offered if you can edit. |
| "No notes match these filters." | The filters hide everything. |
| "No links yet. Type \[\[ in a note to link it to another." | There are notes but no links. |
| "Open a note to see its local graph." | **Local** is on and no note is open. |
| "This note has no links yet. Type \[\[ in a note to link it." | The centre note of a local graph has no links. |
How to make links is in [Links and backlinks](/docs/guide/links).
### Under a spoiler horizon [#under-a-spoiler-horizon]
When a [spoiler horizon](/docs/guide/canon#the-spoiler-horizon) is on, the graph draws only the notes the audience knows by then.
## Codex [#codex]
The world of the story as pages to read: a list on the left, the page on the right. Open it from the ribbon, with "Open codex", or with `⌘⇧C`.
### Sections [#sections]
The top of the left column lists the sections, each with a count:
* **Characters**, **Locations**, **Research** and **Notes**, in the project's own words for them.
* One section for each world-entry type, such as Factions or Objects, when the project has them. See [The world bible](/docs/guide/canon#the-world-bible).
Click a section to list its entries, in alphabetical order. The codex opens on the section of the note you had open, or on Characters.
Scenes, chapters and folders are not in the codex.
### Finding and creating [#finding-and-creating]
* The **Find in…** box filters the section by title and alias.
* The **+** beside it creates a new entry of that section's kind, called "Untitled character" (or location, and so on), and shows it. It needs edit access to the project.
### The page [#the-page]
| Part | What it shows |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Top line | The kind, the note's aliases after "also", and "revealed in" with a release's name if the note has one. With the World bible module on, the [canon status](/docs/guide/canon#canon-status) too. |
| Title and **Edit** | **Edit** opens the note in the editor in a new tab. `⌘`-click opens it to the right. |
| Synopsis | In italics under the title. |
| Tags | The note's tags. |
| The text | The note itself, read-only. |
| Properties | The note's fields and their values, in a box at the side. |
| **Mentioned in** | Every note that links to this one. Click one to open it. `⌘`-click opens it in a new tab. "Nothing links here yet." when there are none. |
The codex is for reading. To change anything on the page, click **Edit**.
With the World bible module on, an entry whose canon status is not Canon or Draft has a coloured dot beside its name in the list. Point at it for the status.
### Entry types [#entry-types]
With the World bible module on, and edit access to the project:
* **New type…** at the bottom of the section list creates a world-entry type.
* Point at a type's section and click the gear to change the type and its fields.
Both open the type dialog described in [The world bible](/docs/guide/canon#the-world-bible).
### A shared world [#a-shared-world]
If the project uses another project's world bible, two buttons appear at the top of the left column: **This project** and the name of the shared world. The second shows the shared world's characters, locations and entry types.
A shared entry is read-only here. Its page says which world it comes from, and **Open** and the world's name goes to that project. To link to a shared entry from your own notes, type `[[` and its name. See [Shared worlds](/docs/guide/links#shared-worlds).
Following a link to a shared entry opens the codex on that entry.
### Under a spoiler horizon [#under-a-spoiler-horizon-1]
When a [spoiler horizon](/docs/guide/canon#the-spoiler-horizon) is on, entries the audience does not know yet are left out of your own project's sections, and the foot of the list says how many: "3 not revealed yet at this point". The shared world's entries are not filtered.
## Relationships [#relationships]
A map of the project's characters with a labelled line for each relationship between two of them. Open it from the ribbon (its button is labelled **Relations**), with "Open relationship map", or with `⌘⇧R`.
Every character note is on the map, as a pill with its initial, its name and how many relationships it has. Other kinds of note are not.
### Adding a relationship [#adding-a-relationship]
1. Press on a character's initial (the circle at the left of the pill).
2. Drag to another character and let go anywhere on it.
3. The relationship is created as **Ally** and its panel opens. Choose the type you want.
You need to be able to edit the character you drag from. A character cannot be related to itself. Two characters can have more than one relationship; the lines bow apart so each can be read.
### Editing a relationship [#editing-a-relationship]
Click a line, or its label, to open the panel at the top right. Its heading shows the two names with `→` for a one-way relationship and `↔` for a mutual one.
| Field | What it does |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Type** | One of the built-in types, or **Other…** to type your own, such as "betrayed" or "owes a debt to". Up to 80 characters. |
| **Label** | Text shown on the map instead of the type's name. Up to 80 characters. |
| **One-way** | Draws an arrowhead pointing at the second character. |
| **Reverse** | Swaps the two characters, so the arrow points the other way. |
| **Delete relationship** | Removes it at once. |
Editing and deleting need edit access to the first character of the pair. **Reverse** needs edit access to both. Without it, the panel shows the relationship but its fields are greyed out.
### Relationship types [#relationship-types]
| Type | Colour | Direction |
| ------------- | ----------- | --------- |
| Ally | Green | Mutual |
| Friend | Cyan | Mutual |
| Family | Blue | Mutual |
| Parent of | Violet | One-way |
| Love interest | Pink | Mutual |
| Mentor of | Orange | One-way |
| Rival | Dark orange | Mutual |
| Enemy | Red | Mutual |
| Works for | Grey | One-way |
The key is along the right of the toolbar. A one-way type always has an arrow, from the character you dragged from to the one you dropped on: drag from the parent to the child for "Parent of". A type you typed yourself is drawn in grey and is mutual unless you tick **One-way**.
### The toolbar [#the-toolbar]
| Button | What it does |
| ----------------------- | ---------------------------------------------------------------------------------- |
| **Character** | Creates a new character note without opening it. Needs edit access to the project. |
| **Only related** | Hides characters that have no relationships. |
| **Arrange in a circle** | Forgets the positions you set and puts everyone back on a circle. |
| **Fit everything** | Zooms to show the whole map. |
### Arranging the map [#arranging-the-map]
Drag a character by its name to move it. Characters start on a circle. You can also drag a character from the binder and drop it where you want it.
Double-click a character to open its note in a new tab. Scroll to zoom and drag the background to pan; the buttons at the bottom left zoom and fit.
Positions are kept in your browser, for this project. They do not follow you to another computer, and your co-writers arrange their own. The relationships themselves are stored with the project and are the same for everyone.
### Things to know [#things-to-know]
* You see a relationship only if you can see both characters.
* Deleting a character for good deletes its relationships. A character in the trash is not on the map.
* The map shows everything, whatever the spoiler horizon is.
* With no characters, the view shows "No characters yet" and a **New character** button.
# Writing goals (/docs/guide/writing-goals)
A daily goal and a streak are the simplest way to keep a draft moving, and Plotra does the counting for you.
Open **Stats** from the ribbon (it is under **More**, in **Team and progress**, until you pin it), or run "Open writing stats and goals" from the command palette. Clicking the session count in the status bar opens it too. The view needs no module, and anyone who can open the project can see it.
## The Stats view [#the-stats-view]
Four tiles along the top, then the chart, the goals and the notes with a target.
| Tile | What it shows |
| ---------------- | ---------------------------------------------------------------------------------------------------------- |
| **Today** | Words added to the project today, by anyone. With a daily goal, a bar towards it. |
| **Streak** | Days in a row with writing. Under it, your longest streak when that is longer than the current one. |
| **Project** | Every word in the project that isn't in the trash. With a project target, a bar towards it. |
| **This session** | Words you have typed in this tab. With a session goal, a bar towards it. **Start over** resets it to zero. |
A tile whose goal is met says **Reached** and its bar turns from orange to teal.
## What is counted [#what-is-counted]
There are two counts, and they measure different things.
**The project's words per day.** Each time a note is saved, Plotra compares its word count with the one before and adds the difference to the current hour's total. This is counted for the whole project, not for each person, so if you write with someone else, their words are in the total too. It drives **Today**, the chart and the streak.
**Your session.** The words you typed in this browser tab since you opened the project. It is counted in your browser, only while your cursor is in the note that is changing, so it is yours alone. The one exception: a co-writer typing in the very note your cursor is in is counted as you.
A few things follow from counting this way:
* Pasting text, importing into an open note, or restoring an earlier version changes the project's count like typing does.
* Words you delete are counted separately as "cut". The chart shows words added, so a day spent trimming still shows the new words you wrote.
* Only text notes are counted: folders, chapters, scenes, notes, characters, locations, research notes and world entries. Canvases, timelines and dialogue trees are not.
* Days end at midnight in your own time zone, taken from your browser. The line under the chart names the zone. Two people in different time zones can see the same hour's words on different days.
* The numbers follow a moment behind your typing, because they move when a note is saved.
* What counts as a word is in [Word counts](/docs/guide/editor#word-counts).
## How a session works [#how-a-session-works]
* A session starts at zero when you open the project in a tab.
* Reloading the page keeps it. Opening the project in a new tab or window starts a new one, and closing the tab ends it.
* It is a net count: words you delete while your cursor is in the note come off. It is never shown below zero.
* **Start over** in the Stats view resets it whenever you like.
* The status bar shows it as "N this session", or "N / goal this session" with a session goal, and a tick once you get there. It appears once you have typed something or set a goal. See [The status bar](/docs/guide/vault-and-binder#the-status-bar).
The session is kept in your browser tab and nowhere else. Plotra does not record words per person.
## Goals [#goals]
Set these under **Goals** in the Stats view. Type a number and press `↵` or click away. Clear a field to remove the goal.
| Goal | Whose | What it does | Limit |
| ------------------ | ------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ---------------- |
| **Daily goal** | Yours, in every project | **Today** shows a bar towards it, the chart draws a line at it, and the streak counts days that reached it | 100,000 words |
| **Session goal** | Yours, in every project | **This session** and the status bar show your session's words against it | 100,000 words |
| **Project target** | The project's, the same for everyone | **Project** shows the total word count against it | 10,000,000 words |
Anyone who can edit the project can set the project target. For everyone else the field is greyed out and reads "Set by the project's editors."
Because **Today** counts the whole project, a daily goal in a shared project is met by everyone's words together.
## Streaks [#streaks]
A streak is the number of days in a row that reached your daily goal. Without a daily goal, it counts days with any words added at all.
* A streak is not broken by today until today is over: if you wrote yesterday and haven't yet today, it still stands.
* Changing your daily goal changes the streak, because every past day is measured against the new number.
* Streaks look back one year. **Longest** is the longest run in that year.
* Like **Today**, a streak is built from the project's words, so each project has its own.
## Targets for chapters [#targets-for-chapters]
A chapter has a **Target words** property. Open the chapter, go to **Properties** in the inspector, and enter a number. The Stats view then lists it under **Notes with a target**, with its count, its target and a bar. Click a row to open the note in a new tab.
A note's count includes everything inside it that isn't in the trash, so a chapter counts its scenes.
To give another kind of note a target, add a number property called "Target words" to that kind in the same panel. See [custom fields](/docs/guide/vault-and-binder#custom-fields). You can also show **Target words** as a column in the [Outline](/docs/guide/planning-views#outline).
## The chart [#the-chart]
**Words added per day** shows one bar for each of the last 30 or 90 days; the two buttons switch between them. Beside the heading is the total for the period and the number of days with writing.
* Point at a bar for the day's number, the date, and the words cut that day.
* The dashed line at the top is labelled with a round number at or above the best day. With a daily goal, a second line marks the goal.
* **Table** shows the same days as a table, newest first, with **Added**, **Cut** and, with a daily goal, whether the goal was reached. It is also the version a screen reader can read day by day.
## Where goals are stored [#where-goals-are-stored]
| What | Where | Who sees it |
| ------------------------ | ----------------------------- | ---------------------------------------------- |
| Daily goal, session goal | Your account | Only you, in every project and on every device |
| Project target | The project's settings | Everyone in the project |
| Target words | A property of the note | Everyone who can see the note |
| Words per day | The project, as hourly totals | Everyone in the project |
| Your session | Your browser tab | Only you, until the tab closes |
# Introduction (/docs)
Plotra keeps your manuscript and the world behind it in one linked project, so you stop hunting through docs, spreadsheets and group chats for a detail, and catch the contradictions before a reader does. Think of Obsidian, built for stories, with more than one person in it: scenes, characters, places, a timeline and a plot grid, written together live. Plotra tracks what is canon, who knows which secret, and what readers know as of each book.
The quickest way to see it is to use it. Sign up, then start with a blank page or open a sample project and look around.
## What you get [#what-you-get]
* **Everything about your story, one click away.** Notes link to each other with `[[wiki-links]]`, so the scene you're in leads to every character, place and secret it mentions. Backlinks, embeds, typed properties, tags and a graph come with that. See [Links and backlinks](/docs/guide/links).
* **A new angle when you're stuck.** The same project as prose, a timeline, a storyboard, a corkboard, a plot grid, an outline or a relationship map, side by side in split panes. See [Views](/docs/guide/views).
* **One draft, not five copies of it.** Live co-editing with cursors, comments, suggestions and version history. Share a project by email with a viewer, a commenter or an editor. See [Working together](/docs/guide/collaboration).
* **A world that doesn't contradict itself.** A canon status on every note, releases, and a spoiler horizon that shows the world as your audience knows it at a given book or session. Plus who-knows-what tracking and continuity checks that run on plain rules. See [Canon and the spoiler horizon](/docs/guide/canon).
## Who it is for [#who-it-is-for]
Plotra has eleven project types. Two lead the list:
* **Novel and series writers who build worlds**: one tool for the manuscript and the world behind it.
* **Tabletop game masters**: a wiki built at the spoiler horizon is the player-safe version of a campaign.
Script formats (screenplay, stage, comic, audio) and the production, interactive, localization and research modules are available to everyone.
## Ask an AI about Plotra [#ask-an-ai-about-plotra]
These docs are written to be read by an assistant as well as by you.
* **On any page**, the **Open** menu under the title sends that page to ChatGPT, Claude, Cursor or Scira with a question ready to ask. **Copy Markdown** copies the page so you can paste it into any other assistant.
* **For the whole docs**, give your assistant [`/llms-full.txt`](/llms-full.txt): every page in one plain-text file. [`/llms.txt`](/llms.txt) is the index, with a link to each page.
* **Any page as Markdown**: add `.md` to its address.
# Modules (/docs/modules)
A novelist doesn't need a shot list, and a studio shouldn't have to go without one. Plotra keeps its specialised tools in **modules**: sets of views, commands and inspector sections that a project switches on when it needs them. A new project starts with few, so the screen stays small, and the rest are one click away.
Modules are not a paid feature. Every module works in every project type and on every plan.
## What a module changes [#what-a-module-changes]
Switching a module on can add:
* **views**, which appear under **More** in the ribbon and get an "Open …" command in the command palette;
* **commands** in the command palette;
* **sections of the inspector**, and entries in menus such as the binder's **New** menu or the editor's block menu.
A module belongs to the project, not to you. When it is on, it is on for everyone in the project.
## The ten modules [#the-ten-modules]
| Module | What it is for | Page |
| -------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| **World bible** | Custom entity types, canon status, retcon history and continuity sheets. | [Canon](/docs/guide/canon) |
| **Releases & reveals** | Books, episodes or patches; what each reveals; "world as of release X"; who knows what; foreshadowing. | [Canon](/docs/guide/canon#releases) |
| **Research & sources** | Citations and a bibliography, clipped pages and files, fact-check status per claim. | [Research and sources](/docs/modules/research) |
| **Review & editorial** | Your own status workflow, required reviewers, locked content, beta readers and a changelog per release. | [Review and editorial](/docs/modules/editorial) |
| **Script formats** (Beta) | Screenplay, stage play, comic and audio script elements with industry formatting and Fountain. | [Script formats](/docs/modules/scripts) |
| **Production** (Beta) | Script breakdowns, recording sheets with line status, and shot lists from storyboards. | [Production](/docs/modules/production) |
| **Interactive narrative** (Beta) | Branching dialogue, quests, short strings with limits, and Ink / Yarn / Twine export. | [Interactive narrative](/docs/modules/interactive) |
| **Localization** (Beta) | Side-by-side translation, a glossary, CSV and XLIFF for translators, subtitles. | [Localization](/docs/modules/localization) |
| **Publishing** | EPUB, manuscript and script formats, a series bible, and a spoiler-safe public wiki. | [Publishing](/docs/modules/publishing) |
| **AI agent** | Ask questions about the project and rewrite or continue text, on each person's own model. | [The AI agent](/docs/guide/ai) |
## What each one adds to the screen [#what-each-one-adds-to-the-screen]
| Module | Views | Commands | Inspector and menus |
| ------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **World bible** | Continuity | "Open continuity" | Canon status in the **Story** tab and in "Tag block". Kinds of your own (Faction, Object and seven more to begin with) in the binder's **New** menu, under **Change kind** and as sections of the Codex. **Born** and **Died** on characters. |
| **Releases & reveals** | Release roadmap, Secrets & setups | "Open release roadmap", "Open secrets & setups" | "Revealed to the audience" in the **Story** tab, and a reveal in "Tag block". The spoiler horizon, "World as of". |
| **Research & sources** | Sources | "Open sources" | **Citation** in the editor's block menu (`/`). A fact-check claim in "Tag block". The **Story** tab. |
| **Review & editorial** | Reviews | "Open reviews" | A review section in the inspector's Properties. Reactions on a passage, for anyone who can comment. Reviewers for stages that need approval. |
| **Script formats** | None | "Import Fountain…", "Export as Fountain" | The format switcher on a note: Prose, Screenplay, Stage play, Comic script, Audio script. |
| **Production** | Production | "Open production" | A breakdown tag (cast, props, wardrobe and so on) in the toolbar that appears when you select text. **Played by** on characters. |
| **Interactive narrative** | Quests, Strings | "Open quest designer", "Open strings (short-text fields)" | **Dialogue** as a kind of note in the **New** menu. A Quest kind. "Strings and dialogue lines" as a scope in the Translate view. |
| **Localization** | Translate | "Open translate" | None. |
| **Publishing** | Publish | "Open publish" | None. |
| **AI agent** | AI | "Open AI chat", "Ask AI…", "AI: Draft this scene or chapter", "AI: Check this chapter", "AI: Carry a change through the project…", "AI: Build the project from a premise…" | An **AI** tab in the inspector. |
The inspector's **Story** tab is there when any of World bible, Releases & reveals or Research & sources is on.
The views that need no module (Graph, Codex, Outline, Plot grid, Relationships, Corkboard, Manuscript, Read, Activity, Stats) are described in [Views](/docs/guide/views).
## Which modules a project starts with [#which-modules-a-project-starts-with]
The project's type decides. A novel starts with none; a screenplay starts with Script formats; a tabletop campaign starts with World bible and Releases & reveals. The full table is in [Project types](/docs/reference/project-types#modules-what-starts-on-and-what-the-type-is-meant-for).
A sample project has every module its type is meant for switched on.
## Switching a module on [#switching-a-module-on]
Only people who manage the project can: the workspace's owner and admins. A member or a guest editor sees the modules that are on, but is not offered the others.
There are four places:
| Where | How |
| ------------------------------------------- | ------------------------------------------------------------------------------ |
| **Project settings → Modules** | Tick the module. See [Project settings](/docs/guide/project-settings#modules). |
| **More → More tools** in the ribbon | Lists the modules "Not switched on in this project". Choose one. |
| A step of the **Getting started** checklist | A step that needs a module shows **Turn on …**. |
| **Project settings → Kinds** | **Turn on World bible**. |
The last three open the same prompt: "Turn on *module*?", with what it is and the views it adds. Press **Turn on**, or **Not now** to leave things as they are. Plotra confirms with "*Module* is on."
The new views appear under **More** in the ribbon, for everyone in the project, straight away. To keep one in your ribbon, see [Customising the ribbon](/docs/guide/project-settings#customising-the-ribbon).
The first time a module is on, Plotra adds what it relies on, the next time someone who can edit opens the project:
* World bible: the nine starting kinds, if the project has no kinds yet, and **Born** and **Died** on characters;
* Interactive narrative: the Quest kind;
* Production: **Played by** on characters.
## Switching a module off [#switching-a-module-off]
Untick it under **Project settings → Modules**. That is the only place.
Nothing is deleted. The module's views, commands and inspector sections go away, and everything made with them stays in the project for when you switch it back on. In particular:
* Notes stay in the binder. A dialogue or a world entry is still there and still opens, even though the **New** menu no longer offers that kind.
* A note written in a script format stays in that format, and keeps its format switcher.
* Releases, reveals, canon statuses, who-knows-what entries, translations, reviews and breakdown tags are kept. They are simply not shown.
* The module's views are gone from **More**, from the ribbon and from the command palette, for everyone.
In the Modules list, a module you have switched by hand is tagged **set by you**. It then stays as you set it even if the project's type changes. Put it back to the type's default and the tag goes.
## Beta modules [#beta-modules]
Four modules carry a **Beta** tag: **Script formats**, **Production**, **Interactive narrative** and **Localization**. They are the newer modules, built and open to everyone on every plan. The tag is shown wherever the module is offered, and on the project types that are built around them.
If something in a Beta module is wrong, [open an issue](https://github.com/ItzSudhan/plotra/issues).
## The AI agent is opt-in [#the-ai-agent-is-opt-in]
The AI agent is the one module no project type starts with, and the one that needs a second switch.
1. An owner or admin switches AI on for the **workspace**, in the workspace's settings.
2. Only then does **AI agent** appear in **Project settings → Modules**. Tick it for each project that should have it. It is never listed under **More tools**.
3. Each person who uses it must be able to edit the project, and needs a model to run it on.
Notes the agent reads are sent to the provider that person chose. See [The AI agent](/docs/guide/ai).
# Keyboard shortcuts (/docs/reference/keyboard-shortcuts)
Almost everything in a project can be done without the mouse. This page lists every command, the keys it starts with, and the keys the editor has built in.
The same list is in the app: press `⌘/`, or choose **Keyboard shortcuts** from **More** in the ribbon or from the user menu. The list in the app shows the keys as you have set them and only the commands this project has.
This page writes keys the way a Mac shows them. On Windows and Linux, use `Ctrl` for `⌘` and `Alt` for `⌥`; the app shows them as `Ctrl+Shift+P`.
## How shortcuts work [#how-shortcuts-work]
* A command's shortcut works anywhere in the project, including while you are typing in the editor.
* A shortcut that has neither `⌘` nor `⌥` in it, apart from the function keys, is ignored while you are typing in a text box, so a key you bind on its own doesn't get in the way of writing.
* Every command is also in the command palette (`⌘P`), with its current keys beside it. A command without keys can still be run from there.
* Some shortcuts are also used by the browser. `⌘P` is the browser's Print and `⌘O` its Open; inside a project, Plotra takes them.
## Changing a shortcut [#changing-a-shortcut]
1. Press `⌘/` to open **Keyboard shortcuts**.
2. Find the command. The search box matches the name, the group, or the keys, typed as shown (`⌘P`) or spelled out (`mod+p`).
3. Click the keys at the right of its row (or **None**, if it has no shortcut). The row shows "Press keys…".
4. Press the new combination.
| While it says "Press keys…" | What happens |
| --------------------------- | --------------------------------------------------------------------------------- |
| Any combination | Becomes the command's shortcut. If another command had it, that command loses it. |
| `⌫` or `Delete` | Removes the shortcut. The command shows **None**. |
| `Esc` | Cancels. |
A row you have changed shows a **Reset to default** button, which gives it back the keys it started with.
The rows under **Editor (fixed)** can't be changed.
### Where changed shortcuts are stored [#where-changed-shortcuts-are-stored]
Changed shortcuts are stored in your browser, not in your account. They apply to every project you open in that browser, and they don't follow you to another browser or computer. Clearing the site's data resets them. If the browser can't store them at all (a private window, or full storage), a change lasts until you close the tab.
## Navigate [#navigate]
| Command | Keys |
| -------------------- | ----- |
| Open command palette | `⌘P` |
| Quick switcher | `⌘O` |
| Search project | `⌘⇧O` |
In the quick switcher, `↵` opens the note, `⌘↵` opens it in a new tab and `⌘⌥↵` opens it to the right. See [Finding things](/docs/guide/vault-and-binder#finding-things).
## Binder [#binder]
| Command | Keys |
| ---------------------------------------------- | ------ |
| New note | `⌘⌥N` |
| New folder | `⌘⌥⇧N` |
| New scene | |
| New chapter | |
| New character | |
| New location | |
| New research | |
| New canvas | |
| New timeline | |
| New dialogue (with **Interactive narrative**) | |
| Rename current note | `F2` |
| Reveal current note in binder | |
| Duplicate current note | |
| Move current note to trash | |
| New beat sheet (Save the Cat, Hero's Journey…) | |
If the project has its own words for the kinds, the commands use them: "New session" in place of "New chapter". "Current note" is the note in the active tab, or the one selected in the binder if no note is open.
With the binder itself focused, these keys work as well. They are fixed.
| Keys | What it does |
| --------------- | ----------------------------------------- |
| `↑` `↓` | Move the selection |
| `→` | Open a folder, then go to its first note |
| `←` | Close a folder, then go to its parent |
| `↵` | Open the note, or open and close a folder |
| `⌘↵` | Open the note in a new tab |
| `⌘⌥↵` | Open the note to the right |
| `⌫` or `Delete` | Move the note to the trash |
With the mouse: click opens a note in the current tab, `⌘`-click or middle-click in a new tab, and `⌘⌥`-click to the right. The same goes for a link in the text. See [Working in the binder](/docs/guide/vault-and-binder#working-in-the-binder).
## Panes [#panes]
| Command | Keys |
| ------------------------ | ----- |
| Close tab | `⌥W` |
| Split right | `⌘⌥\` |
| Split down | |
| Next tab | `⌘⌥→` |
| Previous tab | `⌘⌥←` |
| Pin or unpin tab | |
| Maximize or restore pane | `⌘⇧M` |
| Saved layouts… | `⌘⇧L` |
See [Tabs and panes](/docs/guide/vault-and-binder#tabs-and-panes).
## View [#view]
| Command | Keys |
| ---------------------- | ----- |
| Toggle binder | `⌘\` |
| Toggle inspector | `⌘⇧\` |
| Toggle light / dark | |
| Close all tabs | |
| Show comments | |
| Show version history | |
| Show tags | |
| Show backlinks | `⌘⇧B` |
| Show canon and reveals | |
The "Show" commands open the matching panel of the inspector, or the tags pane on the left.
## Views [#views]
Each view has a command that opens it. Three have keys to begin with.
| Command | Keys | Needs |
| ----------------------------------------------- | ----- | ------------------------- |
| Open graph view | `⌘G` | |
| Open codex | `⌘⇧C` | |
| Open relationship map | `⌘⇧R` | |
| Open outline | | |
| Open plot grid | | |
| Open corkboard of current folder | | |
| Open manuscript (Scrivenings) of current folder | | |
| Read / print preview of current folder | | |
| Open activity feed | | |
| Open writing stats and goals | | |
| Open local graph of current note | | |
| New timeline | | |
| Open release roadmap | | **Releases & reveals** |
| Open secrets & setups | | **Releases & reveals** |
| Open continuity | | **World bible** |
| Open sources | | **Research & sources** |
| Open reviews | | **Review & editorial** |
| Open production | | **Production** |
| Open quest designer | | **Interactive narrative** |
| Open strings (short-text fields) | | **Interactive narrative** |
| Open translate | | **Localization** |
| Open publish | | **Publishing** |
| Open AI chat | | AI switched on |
The commands "of current folder" open on the folder or chapter that is selected, or on the one the open note is in. See [Views](/docs/guide/views).
## Writing [#writing]
| Command | Keys |
| -------------------------------------- | ----- |
| Toggle focus mode | `⌘⇧F` |
| Toggle typewriter scrolling | `⌘⇧T` |
| Toggle suggesting (track changes) | `⌘⇧E` |
| Comment on selection | `⌘⌥M` |
| Tag block (canon, reveal, fact-check)… | `⌘⌥T` |
`Esc` leaves focus mode. See [Focus mode](/docs/guide/editor#focus-mode), [Suggestions](/docs/guide/collaboration#suggestions) and [Block tags](/docs/guide/editor#block-tags).
## File [#file]
| Command | Keys | Needs |
| ---------------------------------------------------- | ---- | ----------- |
| Import… (Markdown, Word, plain text, Obsidian vault) | | Edit access |
| Export… (Markdown, Word, plain text, PDF) | | |
See [Import and export](/docs/guide/import-export).
## Script [#script]
Only with the **Script formats** module on.
| Command | Keys |
| ------------------ | ---- |
| Import Fountain… | |
| Export as Fountain | |
See [Scripts](/docs/modules/scripts).
## AI [#ai]
Only where AI is on for the workspace and the project, and for people who can edit.
| Command | Keys |
| --------------------------------------- | ---- |
| Ask AI… | |
| AI: Draft this scene or chapter | |
| AI: Check this chapter | |
| AI: Carry a change through the project… | |
| AI: Build the project from a premise… | |
In the editor, `⌘J` opens the AI menu on the selection. That key belongs to the editor and can't be changed. See [AI](/docs/guide/ai).
## App [#app]
| Command | Keys |
| ----------------------------------------------------------------- | ---- |
| Project settings (type, modules, workflow)… | |
| Customize: ribbon, inspector and the look of the page | |
| Keyboard shortcuts | `⌘/` |
| Back to the workspace (or "Back to shared projects", for a guest) | |
## Editor (fixed) [#editor-fixed]
These belong to the editor. They work while the cursor is in the text and can't be changed.
### Formatting [#formatting]
| Keys | What it does |
| ------------------- | --------------------- |
| `⌘B` | Bold |
| `⌘I` | Italic |
| `⌘U` | Underline |
| `⌘⇧X` | Strikethrough |
| `⌘E` | Inline code |
| `⌘⇧H` | Highlight |
| `⌘K` | Link to a web address |
| `⌘⌥1`, `⌘⌥2`, `⌘⌥3` | Heading 1, 2 and 3 |
| `⌘⇧.` | Quote |
### Moving and undoing [#moving-and-undoing]
| Keys | What it does |
| ---------------------------------- | --------------------------------- |
| `⌘↵` | New paragraph below the block |
| `⌘⇧↵` | New paragraph above the block |
| `⌘Z` | Undo |
| `⌘⇧Z` | Redo |
| `↵` or `↓` at the end of the title | Move from the title into the text |
| `Esc` in the title | Put the old title back |
### Typed in the text [#typed-in-the-text]
| Type | What it does |
| ---------------------------- | --------------------- |
| `/` | Opens the block menu |
| `[[` | Links to a note |
| `![[` | Embeds a note |
| `#name` | Tags the note |
| `#`, `##`, `###` and a space | Heading 1, 2, 3 |
| `-` or `*` and a space | Bulleted list |
| `1.` or `1)` and a space | Numbered list |
| `[ ]` or `[x]` and a space | To-do, open or ticked |
| `>` and a space | Quote |
| `---` or `___` | Divider |
| `**text**` | Bold |
| `*text*` or `_text_` | Italic |
| `***text***` | Bold and italic |
| `~~text~~` | Strikethrough |
| `==text==` | Highlight |
| `` `text` `` | Inline code |
| `[text](address)` | Link to a web address |
| `--` | Em dash |
| `...` | Ellipsis |
| `->` | Arrow |
| `(c)` | Copyright sign |
Straight quotes become curly ones as you type. With the **Research & sources** module on, `[@` starts a citation.
### In a script [#in-a-script]
In a note written in a script format, `Tab` and `Shift+Tab` change the element the line is: scene heading, action, character, dialogue. See [Scripts](/docs/modules/scripts).
The editor's blocks, toolbar and menus are described on [The editor](/docs/guide/editor).
## Elsewhere [#elsewhere]
| Where | Keys | What it does |
| ----------------------------------------------------- | ------------------- | --------------------------------------- |
| Command palette, quick switcher, saved layouts | `↑` `↓`, `↵`, `Esc` | Move, choose, close |
| A drawer or a dialog | `Esc` | Close it |
| The edge of the binder or the inspector, when focused | `←` `→` | Make the sidebar narrower or wider |
| A tag, alias or multi-select field | `↵` or `,` | Add what you typed |
| The same field, when empty | `⌫` | Remove the last one |
| A property field | `↵`, `Esc` | Keep the value, or put the old one back |
| A tab | Middle-click | Close it |
The views have keys of their own, for example `⌘` and scroll to zoom the timeline. See [Views](/docs/guide/views) and the pages for each view.
# Project types (/docs/reference/project-types)
A project's type is a preset. It picks the modules that start switched on, the format a new scene is written in, and what a release is called. It locks nothing: every module can be switched on in any type, and the type itself can be changed later under [Project settings](/docs/guide/project-settings#general).
You choose the type when you create the project, in the [new project dialog](/docs/guide#the-new-project-dialog) or under "What are you making?" in [the cold open](/docs/guide#the-cold-open).
## The types at a glance [#the-types-at-a-glance]
| Type | For | Starts with | New scenes | A release is a | Beta |
| -------------------------- | ------------------------------------------------------------ | ------------------------------- | ------------ | -------------- | ---- |
| **Novel / series** | A book, or several set in one world. | The essentials | Prose | Book | |
| **Web serial** | Fiction published a chapter at a time. | The essentials | Prose | Chapter | |
| **Short story** | A single short piece. | The essentials | Prose | Other | |
| **Screenplay / TV** | A film, a pilot or a series. | Script formats | Screenplay | Episode | Beta |
| **Stage play** | A play in acts and scenes. | Script formats | Stage play | Other | Beta |
| **Comic / manga** | A script in pages and panels. | Script formats | Comic script | Issue | Beta |
| **Game / interactive** | Branching dialogue, quests and in-game text. | Interactive narrative | Prose | Patch | Beta |
| **Tabletop RPG** | A campaign: sessions, NPCs, and what the players don't know. | World bible, Releases & reveals | Prose | Session | |
| **Podcast / audio drama** | A script for voices, sound and music. | Script formats | Audio script | Episode | Beta |
| **Non-fiction / research** | A book or a study built on sources. | Research & sources | Prose | Book | |
| **Franchise / IP bible** | One world shared by books, shows and games. | World bible | Prose | Book | Beta |
"The essentials" means no module at all: the editor, the binder, links, and the views that are always there. See [Views](/docs/guide/views#views-that-are-always-there).
## Modules: what starts on, and what the type is meant for [#modules-what-starts-on-and-what-the-type-is-meant-for]
A new project starts with only the modules its type can't be written without. The rest of the type's tool set is one click away: Plotra [offers a module](/docs/guide#when-plotra-offers-a-module) when a checklist step needs it, and **More → More tools** in the ribbon lists every module that is off.
| Type | On from the start | The type's full tool set |
| ---------------------- | ------------------------------- | -------------------------------------------------------------------- |
| Novel / series | None | World bible, Releases & reveals, Review & editorial, Publishing |
| Web serial | None | Releases & reveals, Publishing |
| Short story | None | Review & editorial, Publishing |
| Screenplay / TV | Script formats | Script formats, Production, Releases & reveals, Publishing |
| Stage play | Script formats | Script formats, Publishing |
| Comic / manga | Script formats | Script formats, Production, Publishing |
| Game / interactive | Interactive narrative | World bible, Interactive narrative, Localization, Releases & reveals |
| Tabletop RPG | World bible, Releases & reveals | World bible, Releases & reveals, Publishing |
| Podcast / audio drama | Script formats | Script formats, Production, Releases & reveals |
| Non-fiction / research | Research & sources | Research & sources, Review & editorial, Publishing |
| Franchise / IP bible | World bible | Every module except the AI agent |
Things to know:
* The full tool set is what a [sample project](/docs/guide#sample-projects) of that type has switched on, and what decides the Beta tag. It is not a limit: **More tools** offers every module in every type.
* A project started from the cold open also gets **Releases & reveals** if your answers made a release, a secret that someone knows, or a line only the game master sees.
* The **AI agent** is never part of a type. It can only be switched on once the workspace allows AI. See [The AI agent](/docs/guide/ai#turning-it-on).
* If you change a project's type, modules you switched on or off yourself stay as they are. The others follow the new type.
What each module adds is on the [Modules](/docs/modules) page.
## The format of new scenes [#the-format-of-new-scenes]
| Format | Types that start with it | What a page is made of |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| **Prose** | Novel / series, Web serial, Short story, Game / interactive, Tabletop RPG, Non-fiction / research, Franchise / IP bible | Paragraphs, headings and lists. |
| **Screenplay** | Screenplay / TV | Scene headings, action, character, dialogue, transitions. |
| **Stage play** | Stage play | Acts and scenes, stage directions, character and dialogue. |
| **Comic script** | Comic / manga | Pages and panels with captions, dialogue and SFX. |
| **Audio script** | Podcast / audio drama | Character lines with delivery notes, sound and music cues. |
The first scene of a new project is in this format, and so is every scene you create after it. Change the default under **New scenes are written as** in the project settings. See [Script formats](/docs/modules/scripts).
## What a release is called [#what-a-release-is-called]
A [release](/docs/guide/canon#releases) is whatever the story ships in. When you add one, its kind starts as the type's own: a book for a novel, a session for a campaign, an episode for a show. You can pick another kind for any single release. The kinds are book, chapter, episode, season, issue, volume, patch, session, beat and other.
Short story and Stage play have no natural unit, so their releases start as "Other".
## The ribbon a project starts with [#the-ribbon-a-project-starts-with]
The ribbon shows five views to begin with. Which five depends on how the project was started, not only on its type. Every other view is under **More**, and you can [rearrange the ribbon](/docs/guide/project-settings#customising-the-ribbon) as you like.
| Project | Views in the ribbon, top to bottom |
| ---------------------------------------------------------- | ------------------------------------------- |
| A novel, or any type but the two below, from the cold open | Graph, Codex, Outline, Draft, Read |
| A tabletop RPG from the cold open | Graph, Codex, Outline, Read, Releases |
| A screenplay from the cold open | Codex, Outline, Corkboard, Draft, Read |
| Any type made with the **New project** dialog | Graph, Codex, Outline, Draft, Read |
| A sample project | Graph, Codex, Releases, Secrets, Continuity |
| A project made from a template | The same as the template's. |
"Draft" is the Manuscript view, "Releases" is the Release roadmap and "Secrets" is Secrets & setups: the ribbon uses the short names.
Releases, Secrets and Continuity belong to modules. They are in the ribbon only while that module is on.
Because the ribbon is saved with your account, a view you pinned, hid or moved in one project is pinned, hidden or moved in all of them.
## What else the cold open sets by type [#what-else-the-cold-open-sets-by-type]
Three types have their own track through [the cold open](/docs/guide#the-cold-open): Novel / series, Tabletop RPG and Screenplay / TV. The other eight share the novel's.
| | Novel / series | Tabletop RPG | Screenplay / TV | The other eight |
| ------------------- | ----------------------------------------- | ----------------------------------------------- | ----------------------------------------------------- | --------------- |
| Extra questions | One book or a series; whose point of view | Who's at the table; what happens in session one | Film, pilot or series; INT. or EXT. | None |
| First page | "Opening", in "Chapter 1" | "Session 1 prep", in "Session 1" | "Opening scene", in "Act One", "Pilot" or "Episode 1" | "First scene" |
| A chapter is called | Chapter | Session | Sequence | Chapter |
| Checklist | Novel | Tabletop | Screenplay | Novel |
A project made with the **New project** dialog gets none of these: it has the app's own words, no checklist, and one empty scene.
## The Beta tag [#the-beta-tag]
A type carries **Beta** when its full tool set includes a module that is in beta: Script formats, Production, Interactive narrative or Localization. Those are the newer modules, built and open to everyone. The tag appears beside the type wherever you choose one, and as "(beta)" in the project settings.
Novels and tabletop campaigns are what Plotra is built around first, which is why those two lead the list of types.
# Self-hosting with Docker (/docs/self-hosting)
Plotra is open source (AGPL-3.0) and everything in it runs on your own machine. One compose file starts the whole thing:
| Service | What it is | Published on |
| ----------------------- | ----------------------------------------------------------- | ------------- |
| `app` | The Plotra web app (Next.js) | port 3000 |
| `collab` | The live-editing server browsers hold a WebSocket to | port 8787 |
| `postgres` | The database (Postgres 18) | not published |
| `minio` | S3-compatible storage for uploads and version snapshots | not published |
| `migrate`, `minio-init` | One-shot jobs: apply database migrations, create the bucket | |
A self-hosted Plotra is free. It has no plans and no limits on projects or storage, needs no account anywhere, and sends no email unless you set that up. The Free and Pro plans exist only on the hosted version: no billing code runs here unless you set it up yourself, as described under [Plans and billing](#plans-and-billing).
Running Plotra yourself means running a server: Docker, a domain, TLS, backups and upgrades are yours to do, and yours to fix when they break. On the [hosted version](https://app.plotra.ink/sign-up) there is nothing to install or look after, the Free plan has every feature, and Pro is $10 a month for a whole workspace. See [Plans and billing](/docs/guide/plans).
Every part of this setup was run outside Docker on the machine it was written on: the standalone build of the app against a plain Postgres 18, the migrations, sign-up, a workspace, a project, file upload through an S3 endpoint, and live editing through the collab server with its state surviving a restart. The compose file was checked with `docker compose config`. The images themselves had not been built when this page was written, because Docker wasn't running there. If a build or a start fails for you, please [open an issue](https://github.com/ItzSudhan/plotra/issues) with the output. When someone has run it end to end, replace this note with the date.
## Requirements [#requirements]
* Docker with Compose v2.20 or newer (`docker compose version`).
* About 2 GB of free memory to build the app image, and 1 GB to run the stack.
* `git` and `openssl`.
* For anything other than `http://localhost`: a domain name and a reverse proxy that does TLS. See [Reverse proxy and TLS](#reverse-proxy-and-tls).
## Quick start [#quick-start]
```bash
git clone https://github.com/ItzSudhan/plotra.git
cd plotra/docker
cp .env.example .env
```
Generate the secrets. This fills every empty secret in `.env`, and leaves filled ones alone if you run it again:
```bash
for name in POSTGRES_PASSWORD BETTER_AUTH_SECRET COLLAB_SECRET S3_SECRET_ACCESS_KEY AI_KEY_SECRET; do
sed -i.bak "s|^$name=\$|$name=$(openssl rand -hex 32)|" .env
done && rm -f .env.bak
```
Start it:
```bash
docker compose up -d --build
```
The first run builds three images and takes a few minutes. When `docker compose ps` shows `app` and `collab` as healthy, open [http://localhost:3000](http://localhost:3000) and sign up with an email and a password. The first account is an ordinary account: there is no admin user to set up.
To check the instance from the command line:
```bash
curl http://localhost:3000/api/health
curl http://localhost:8787/health
```
The first answers `{"ok":true,"database":"ok",…}` and lists which optional services are configured. The second is the collab server, and answers `{"ok":true}`.
Over plain HTTP on any address other than `localhost`, such as `http://192.168.1.20:3000`, browsers switch off features Plotra relies on. Creating notes and the copy buttons stop working. To use Plotra from other devices, put it behind HTTPS.
## Settings [#settings]
Everything is set in `docker/.env`. After changing a value, run `docker compose up -d` again. The two settings marked "build" are compiled into the app, so they need `docker compose up -d --build app`.
### Addresses [#addresses]
| Variable | Default | What it does |
| ------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BETTER_AUTH_URL` | `http://localhost:3000` | The URL people open Plotra at, without a trailing slash. Sign-in cookies, links in emails and the collab server's token check use it, so it must match the browser's address bar exactly |
| `NEXT_PUBLIC_COLLAB_URL` | `http://localhost:8787` | The URL browsers reach the collab server at. **Build** |
| `APP_PORT`, `COLLAB_PORT` | `3000`, `8787` | The host ports the two are published on |
| `APP_BIND`, `COLLAB_BIND` | `0.0.0.0` | The host address they bind to. Use `127.0.0.1` when a reverse proxy on the same machine is the only thing that should reach them |
If you change `APP_PORT` without a reverse proxy, change the port in `BETTER_AUTH_URL` to match. The same goes for `COLLAB_PORT` and `NEXT_PUBLIC_COLLAB_URL`.
### Secrets [#secrets]
| Variable | What it does |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BETTER_AUTH_SECRET` | Signs sessions and tokens. Changing it signs everyone out |
| `COLLAB_SECRET` | Shared by the app and the collab server, so each knows the other is calling |
| `POSTGRES_PASSWORD` | Password of the bundled Postgres. It is set when the database volume is first created. Changing it in `.env` later does not change it in the database |
| `S3_SECRET_ACCESS_KEY` | Password of the bundled file store, and what the app signs its requests with |
| `AI_KEY_SECRET` | Encrypts the AI provider keys people save in Settings. Changing it makes saved keys unreadable |
### What runs [#what-runs]
| Variable | Default | What it does |
| ------------------ | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `COMPOSE_PROFILES` | `postgres,minio,collab` | The optional services. Remove `postgres` to use [your own database](#using-neon-or-another-postgres), `minio` to use [another file store or none](#files), `collab` to run [the collab worker on Cloudflare](#the-self-hosted-collab-server-and-its-limits) |
| `DATABASE_URL` | empty | Empty means the bundled Postgres. Otherwise a Postgres connection string |
| `DATABASE_DRIVER` | empty | `pg` or `neon`. Empty picks `neon` for a `neon.tech` host and `pg` for everything else |
### Files [#files]
Uploads and version snapshots go to an S3-compatible store. The bundled one is MinIO; the defaults in `.env` point at it.
| Variable | Default | What it does |
| ------------------------------------------ | ------------------- | ---------------------------------------------------------------------------- |
| `S3_ENDPOINT` | `http://minio:9000` | The store's URL. The bucket is addressed as `//` |
| `S3_BUCKET` | `plotra` | The bucket. `minio-init` creates it in the bundled store |
| `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` | `plotra`, generated | Credentials. The bundled MinIO takes them as its root user and password |
| `S3_REGION` | empty | The region requests are signed for. Empty means `us-east-1`, MinIO's default |
Nothing outside the stack talks to the store: the app reads and writes files on behalf of browsers. That is why MinIO has no published port.
To use another S3 store (Cloudflare R2, Garage, SeaweedFS, AWS S3), set the five `S3_` values and remove `minio` from `COMPOSE_PROFILES`. Create the bucket yourself.
To run with no store at all, also empty `S3_ENDPOINT`. Files then go into Postgres, with smaller limits: 10 MB a file and 100 MB a project.
MinIO stopped publishing its own Docker image, so the compose file uses `pgsty/minio`, a community-maintained build of the same server, pinned to one release. Set `MINIO_IMAGE` in `.env` to use a different build. Any S3-compatible store works in its place.
### Limits [#limits]
Your own instance has no limit on projects or storage. A single file can be at most 100 MB, and one project's attachments 2 GB together.
The hosted version's limits belong to its Free and Pro plans, which exist only where billing is set up. See [Limits on the hosted version](/docs/guide/quotas).
### Sign-in and email [#sign-in-and-email]
Email and password sign-in works with nothing else set up. Anyone who can reach your instance can sign up. They get their own workspace and see nothing of yours, but if you don't want strangers on it, don't expose it to the internet, or put your reverse proxy's access control in front of it.
| Variable | What it does |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` | Optional. The Google button appears when both are set. Register `/api/auth/callback/google` as the callback URL |
| `SMTP_URL` | Optional. Sends invitations and sharing notices through an SMTP server, at any mail service or your own: `smtps://user:password@smtp.example.com:465`. Use `smtps://` for port 465 and `smtp://` for 587, and percent-encode special characters in the password |
| `EMAIL_FROM` | The sender, such as `Plotra `, at an address that server may send from. Unset, it is the SMTP login |
**Without `SMTP_URL` no email is sent.** Each invitation or sharing link is written to the app's log instead, and you pass it on yourself:
```bash
docker compose logs app | grep '\[plotra\]'
```
```
[plotra] Invitation for grace@example.com to Test Press: http://localhost:3000/invite/WNHMQN8S…
```
### AI [#ai]
Each person adds their own provider key in Settings, which needs `AI_KEY_SECRET`. Or you give the whole instance one model:
| Variable | What it does |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AI_PROVIDER` | `anthropic`, `openai`, `openrouter`, `compatible` (any OpenAI-compatible endpoint) or `ollama` |
| `AI_API_KEY` | The key, for providers that need one |
| `AI_BASE_URL` | For `compatible` and `ollama`. An Ollama on the Docker host is `http://host.docker.internal:11434/v1` |
| `AI_MODEL_AGENT`, `AI_MODEL_FAST` | The models to use. The fast one defaults to the agent one |
| `AI_ALLOW_PRIVATE_URLS` | `true` here, so a model URL may point at this machine or your network, which a local model needs. Set it to `false` if people you don't know can sign up: otherwise they can make your server send requests to addresses inside your network |
### Plans and billing [#plans-and-billing]
**All of this is optional, and off by default.** Without `CREEM_API_KEY` there are no plans at all: no Free or Pro, no checkout, no Plan & billing tab, and no limits on projects or storage. Leave these empty unless you want to charge the people on your instance, the way the hosted version does.
Payments go through [Creem](https://creem.io), a merchant of record. You need your own Creem account and two subscription products in it, one billed monthly and one yearly.
| Variable | What it does |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `CREEM_API_KEY` | Switches plans on. A key that starts with `creem_test_` uses Creem's test API, where no real money moves |
| `CREEM_WEBHOOK_SECRET` | The signing secret of the webhook you register in Creem. The app uses it to check that a webhook really came from Creem |
| `CREEM_PRODUCT_PRO_MONTHLY` | The Creem product id of the monthly Pro subscription |
| `CREEM_PRODUCT_PRO_YEARLY` | The Creem product id of the yearly Pro subscription |
In Creem, register the webhook URL `/api/billing/webhook`. Creem calls it when a subscription starts, renews, is cancelled or ends, which is how a workspace's plan changes. Your instance has to be reachable from the internet for that.
With plans on, a workspace is on Free until it subscribes, and the limits of each plan are the ones in [Plans and billing](/docs/guide/plans). The plan is managed under Workspace settings → Plan & billing (`/w//settings?tab=billing`).
### Hosted AI [#hosted-ai]
Also optional. With plans on, the model set with `AI_PROVIDER` under [AI](#ai) stops being everyone's: it becomes the model that Pro workspaces use with their monthly credits (1,500 a month), so that their members need no key of their own. You pay for these calls.
Without it, Pro workspaces have no hosted AI, and the agent runs on people's own keys as before.
### Other [#other]
| Variable | What it does |
| ----------------------------------------------------------------------------- | --------------------------------------------------------- |
| `SENTRY_DSN` | Optional error tracking. **Build** as well as run time |
| `NEXT_PUBLIC_SITE_URL`, `NEXT_PUBLIC_POSTHOG_KEY`, `NEXT_PUBLIC_POSTHOG_HOST` | Optional, described in `apps/app/.env.example`. **Build** |
| `MINIO_IMAGE` | The image of the bundled file store |
### Why some settings need a rebuild [#why-some-settings-need-a-rebuild]
Next.js compiles every `NEXT_PUBLIC_` value into the JavaScript it sends to browsers. They are fixed when the image is built, not when the container starts. The compose file passes them from `.env` to the build as build arguments, so the image you build carries your values:
```bash
docker compose up -d --build app
```
Everything else is read when the container starts.
## Reverse proxy and TLS [#reverse-proxy-and-tls]
Browsers need to reach two things: the app and the collab server's WebSocket. Neither container does TLS, so put a reverse proxy in front.
Browsers only ever talk to the collab server under `/parties/`, and the app has no pages there. So one domain is enough: send `/parties/*` to the collab server and everything else to the app.
In `.env`:
```bash
BETTER_AUTH_URL=https://plotra.example.com
NEXT_PUBLIC_COLLAB_URL=https://plotra.example.com
APP_BIND=127.0.0.1
COLLAB_BIND=127.0.0.1
```
Then rebuild, because `NEXT_PUBLIC_COLLAB_URL` changed: `docker compose up -d --build`.
With [Caddy](https://caddyserver.com), which gets certificates by itself and handles WebSockets without extra settings:
```
plotra.example.com {
handle /parties/* {
reverse_proxy 127.0.0.1:8787
}
handle {
reverse_proxy 127.0.0.1:3000
}
}
```
With nginx, inside a `server` block that already has your certificate:
```nginx
location /parties/ {
proxy_pass http://127.0.0.1:8787;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_read_timeout 1h;
}
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
client_max_body_size 110m;
}
```
Things that matter whichever proxy you use:
* **Pass the `Host` header through** and set `X-Forwarded-Proto`. The app builds its redirects from them.
* **Set `X-Forwarded-For`.** Rate limits count by client address. Without it everyone shares one limit.
* **Allow WebSocket upgrades and long-lived connections** on `/parties/`.
* **Allow large request bodies** on the app if you want large uploads.
* **Send only `/parties/` to the collab server.** Browsers need nothing else from it.
* Two domains work as well: point `NEXT_PUBLIC_COLLAB_URL` at the second one, such as `https://collab.plotra.example.com`.
The collab container reaches the app directly inside the compose network (`http://app:3000`), not through your proxy. It still needs `BETTER_AUTH_URL` to be the public address, because the tokens it checks name that address as their issuer. The compose file passes both.
## Backups [#backups]
Three volumes hold data, plus your `.env`:
| What | Holds | If it is lost |
| ---------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `plotra_postgres-data` | Accounts, workspaces, projects, every note's text, comments, links | Everything is gone |
| `plotra_minio-data` | Uploaded files and version snapshots | Notes survive. Attachments and older versions don't |
| `plotra_collab-data` | The live state of every note that has been opened | Little: the collab server copies each note to Postgres within 10 seconds of an edit, and reloads from there |
| `docker/.env` | The secrets | Sessions end, and saved AI keys can't be decrypted |
**The database.** `pg_dump` works while the stack is running:
```bash
docker compose exec -T postgres pg_dump -U plotra -Fc plotra > plotra-$(date +%F).dump
```
**The file store.** Archive the volume. Stop the store first for a consistent copy:
```bash
docker compose stop minio
docker run --rm -v plotra_minio-data:/data:ro -v "$PWD":/backup alpine \
tar czf /backup/minio-$(date +%F).tar.gz -C /data .
docker compose start minio
```
The same command with `plotra_collab-data` copies the collab server's state; stop `collab` for it.
**Restoring the database** into a new, empty instance. `pg_dump` does not include roles, so create the one Plotra's row-level security uses before loading the dump:
```bash
docker compose up -d postgres
docker compose exec -T postgres psql -U plotra -d plotra \
-c "create role plotra_app nologin nobypassrls; grant plotra_app to plotra;"
docker compose exec -T postgres pg_restore -U plotra -d plotra --no-owner < plotra-2026-10-02.dump
docker compose up -d
```
When you restore an older database into an instance that has been running, remove the collab volume too (`docker volume rm plotra_collab-data`, with the stack down). Otherwise the collab server still holds the newer text of each note and writes it back over the restored one.
The restore steps above were written without being run. Do one restore into a scratch instance before you rely on your backups.
## Upgrading [#upgrading]
Back up the database first. Then:
```bash
git pull
docker compose up -d --build
```
That rebuilds the images, runs the `migrate` job, and only then starts the new app: the app waits for `migrate` to finish, and does not start if a migration fails. Migrations that were already applied are skipped. To see what it did:
```bash
docker compose logs migrate
```
There are no tagged releases yet, so `git pull` takes the current `master`. Read the commit log for anything that mentions self-hosting before you upgrade.
## Using Neon or another Postgres [#using-neon-or-another-postgres]
The bundled Postgres is optional. To run against [Neon](https://neon.tech) instead, create a project there, copy its connection string, and in `.env` set `DATABASE_URL` to it and remove `postgres` from `COMPOSE_PROFILES` (leaving `COMPOSE_PROFILES=minio,collab`). Then `docker compose up -d --build`: the `migrate` job creates the tables in Neon, and the app connects with Neon's serverless driver, which it picks by itself for a `neon.tech` host. The pooled and the direct connection string both work. Set `DATABASE_DRIVER=pg` if you would rather connect over plain TCP, as the migrations do.
The same goes for any other Postgres: set `DATABASE_URL`, drop the `postgres` profile. Plotra is developed and tested on Postgres 18; older versions have not been tried. One requirement holds everywhere. The role in the connection string must own the database and be allowed to create roles, because a migration creates `plotra_app`, the role without privileges that every user request runs as so that Postgres row-level security applies to it. Neon's default role qualifies. On your own server, a superuser does, or a role with `CREATEROLE` that owns the database.
## The self-hosted collab server and its limits [#the-self-hosted-collab-server-and-its-limits]
On the hosted version the collab server is a Cloudflare Worker with one Durable Object per open note. The `collab` container runs that same worker, unchanged, under `workerd`, Cloudflare's open-source runtime, started through `wrangler dev`. Its storage is one SQLite file per note under `/data`, on the `plotra_collab-data` volume.
That keeps one codebase for both, and it has limits you should know:
* **It is Cloudflare's local development mode.** It is the same runtime, but Cloudflare does not offer it as a production server. It has been run here for editing by a few people at once, not under load.
* **One process, one machine.** It cannot be scaled out by running more copies: two copies would each hold their own version of a note.
* **Every open note is held in memory** until everyone has left it.
* **It builds the worker each time the container starts**, which takes a few seconds. The `collab` service waits for the app to be healthy first.
* **It does no TLS.** Browsers on an HTTPS page can only connect to it through a proxy that does.
* **Its files are in Miniflare's format**, which could change with a new major version of `wrangler`. The version is pinned by the repo's lockfile. Postgres has a copy of every note, so an emptied `/data` reloads from there.
* **It contacts the internet on start** to look for a newer `wrangler` and to fetch request metadata from Cloudflare. Both fail quietly without a connection, and usage reporting is switched off.
* **`wrangler dev` has a debugging interface** that can read the stored notes. The container switches it off (`X_LOCAL_EXPLORER=false` in `docker/collab-entrypoint.sh`). Keep that setting if you write your own entrypoint, and proxy only `/parties/` as shown above.
If these limits matter to you, you can deploy `apps/collab` to your own Cloudflare account instead (the free plan covers it) and point `NEXT_PUBLIC_COLLAB_URL` at it. Set its `APP_URL` to your `BETTER_AUTH_URL` and its `COLLAB_SECRET` to yours, and remove `collab` from `COMPOSE_PROFILES`. Your app then has to be reachable from the internet, because the worker calls it.
## Troubleshooting [#troubleshooting]
| What you see | Likely cause |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `required variable BETTER_AUTH_SECRET is missing a value` | No `docker/.env`, or the secrets were not generated |
| `migrate` exits with an error about permissions or roles | The database role may not create roles. See [Using Neon or another Postgres](#using-neon-or-another-postgres) |
| The editor stays on "Connecting…" | The browser cannot reach `NEXT_PUBLIC_COLLAB_URL`, or it changed and the app image was not rebuilt, or `BETTER_AUTH_URL` is not the address in the browser |
| `collab` logs `Couldn't seed … 401` | `COLLAB_SECRET` differs between the app and the collab server. Both read it from `.env`: run `docker compose up -d` |
| Signing in fails, or doesn't stick | `BETTER_AUTH_URL` is not the address in the browser: `https` against `http`, another host, or another port |
| Creating a note does nothing | Plain HTTP on an address other than `localhost`. See the note under [Quick start](#quick-start) |
| `minio` keeps restarting | `S3_SECRET_ACCESS_KEY` is empty or shorter than 8 characters |
To start over and delete all data: `docker compose down -v`.