Parlance

Setting up writers to contribute

Parlance lets writers contribute to your game through the app, without a terminal, a manual clone, or hand-editing JSON. Your git repository stays the single source of truth — Parlance hosts nothing, and no writer's words pass through any server of ours.

This guide is for the person setting a team up. It covers what a writer does, what you do once per writer, and — plainly — what the security model does and does not give you.

How it works

A writer signs in to your git host inside the app, opens your project by cloning it, and edits their scenes. When they click Send for review, the app quietly creates a branch, commits, pushes, and opens a review request — the writer never sees any of it. You review in the app and merge. The writer's mental model is drafts and submissions; the git is underneath, run by the app.

Each writer works on their own draft branches (writer/<name>/…), so two people rarely touch the same file, and a genuine conflict is escalated to a person rather than shown to the writer as a merge to resolve.

For writers

Everything is in the Drafts panel. There is no git here — only drafts.

  1. Start a draft and write. If you already made some edits, the app offers to start the draft with those changes.
  2. When it's ready, press Send for review. That's the whole hand-off — the draft moves to "In review". If you're offline it's kept on your computer and sent next time you press Send.
  3. If the owner asks for changes, the draft says so; make them and press Send changes.
  4. When the owner publishes it, the draft reads In the game on its own (usually within a minute). Press Clean up to tidy it away.

A draft that's approved reads "Approved — waiting to be published": there's nothing for you to do — the owner publishes it. An "unsent changes" tag means you've edited since you last sent; press Send again to share them.

The Send for review dialog has an optional Note for the reviewer. The owner sees it with the draft when they open it in Review. Later sends (Send changes, Send update) go into the same review under the same title. Their dialog shows the note field again, but only the first send's note is kept, so answer the owner by replying to their comments instead.

When notes come back

The owner's comments are pinned to the line they're about, not to a line number, so they still point at the right place after you edit. A comment can carry Suggested text: the wording the owner would use. It is a proposal; your scene is unchanged until you apply it.

  1. Get the notes. In the Drafts panel, press Get review notes on the draft you are in (opening a different draft with Open fetches its notes too). If you have changes you haven't sent and new notes are waiting, the app refuses and changes nothing: Send changes first — sending brings the notes in as well.
  2. Find them. Open Review and expand Advanced: compare any two branches. Your draft is already filled in, and your review is listed under Reviews on this branch. Pick it; the header reads AUTHORING, and the comments appear beside the changes. (Opening the same draft from "Reviews waiting for you" shows it read-only, as a reviewer sees it, and suggestions can't be applied from there.)
  3. Apply a suggestion. Press Apply suggestion under the suggested text. It replaces that line in your scene, marks the comment resolved, and records "applied by" with your name. If the line has since been deleted, the app says the suggestion can't be applied. You can also reply to a comment, or just edit the scene yourself.
  4. Send changes when you're done.

For owners: reviewing and publishing

Open Review. The "Reviews waiting for you" list shows every writer's draft by title and author — no branch names, nothing to check out.

  1. Open a draft. Read the summary of what changed and, if you like, open a scene to see the before/after or play the branch as it stands.
  2. Comment on anything. Your comments are sent when you publish (or you can send them on their own).
  3. Approve & publish in one click. The change goes into the game with a plain-language confirm — and your own open files are never touched. Whatever branch you're on, whatever unsaved work you have, publishing leaves it exactly as it was.

If a draft overlaps with something already in the game, publishing refuses in plain words and changes nothing — that's the one case where someone comfortable with git combines the two. Publishing needs git 2.38 or newer on your computer; older git is refused with a notice to update. New drafts appear on their own while the panel is open — no need to refresh.

The app publishes to the shared game. If you also edit the game directly outside the app, pull first so your copy is current.

Providers

Self-serve sign-in works for GitHub, GitLab (gitlab.com and self-managed) and Bitbucket Cloud:

Any git host also works without self-serve sign-in if you set up the writer's machine yourself once (a clone plus credentials); the app then drives the rest.

One-time studio setup

  1. Give the writer access to the repository. Add them as a collaborator (GitLab: a project member with at least Developer access; Bitbucket: write access). The writer accepts the invitation from their email or account page — until they do, the repo will not appear in the app's picker.
  2. Tell them which project to open. They pick it from a list of repositories they can push to; point them at the right one by name.
  3. On GitHub only — install the Parlance app on your repository. A GitHub sign-in can reach a private repo only once the Parlance GitHub App is installed on it. A repository admin opens the app's page on GitHub, chooses Install, selects the repository, and confirms — once, for the whole team. GitLab and Bitbucket need no app install; the collaborator invite in step 1 is enough on those hosts.

That is the whole studio-side setup. There is nothing of ours to run or host on your end.

Per-writer setup

The writer does this once, in the app:

  1. Sign in. Open Git accounts. For GitHub, click Sign in with GitHub and approve the short code it shows you at github.com — nothing to paste. For GitLab or Bitbucket, choose the provider, click Open token page — for GitLab the token's name and permissions are pre-filled, so it is two clicks; for Bitbucket follow the short numbered steps — then paste the token back. The app checks the sign-in before saving it, so a bad one fails immediately and stores nothing.
  2. Open the project. Open from repository, pick the repo, choose where it lands. The app clones it and opens it. From then on the writer just opens the app and writes.

The minimum token permissions the app asks for are exactly what it needs and no more: clone/push plus reading the list of repositories and the account name. Nothing administrative.

What enforcement you actually get — read this

Method A gives every writer read access to the whole repository and lets the app keep their writing on their own branches. Be clear-eyed about what that is and isn't:

None of this is a reason not to use Method A — it is the right tool for a team that trusts its writers. It is a reason to know which repositories you point it at.

Tokens and revoking access

Writers who won't create an account

Some writers won't make a git account at all. They don't have to. They can write in a plain screenplay-style text format and send it in; a trusted operator (or a coding agent, via the ingest-dialogue skill) converts it to game data and puts it through the same review. See tooling/llm/WRITER_TEMPLATE.md. Method A is for writers willing to install the app and sign in; the template path catches everyone else.

Troubleshooting

Generated from Orbitope/parlance @ 8c601ef on 2026-09-28 — do not edit on this site.