# AI assistance

> How machine help works in Kwark, step by step. A machine may measure the work, find things in it, carry it into production, move the writer's own words, convert how they are typed, read it aloud, or prepare it for a tool the person chooses. Every proposal is marked, sourced, offered one at a time, undoable and never a judgement.

Source: https://kwark.space/designSystem/patterns/ai-assistance

## The problem

A director has the screenplay of Blank Pages and a five-day shoot. Every prop, costume and location has to be pulled out of 96 pages into a breakdown before anyone can schedule. A machine can do much of that reading. But the same week, other tools offer to score her script, rewrite Mira's dialogue "for impact", and fill the breakdown in one click with forty items she has never seen.

The danger is not that a machine is wrong; it is that its guesses become the work without anyone choosing them, and that a tool built for writers starts telling them whether their writing is good. The founder: "right now the industry has not understood how to use AI in scripting, and I want to be mindful".

So the question for every feature is not "can a machine do this" but "who is the author afterwards". In Kwark the answer is always the person.

## Kwark's answer

Decision 0002 sets the line: **no AI feedback, scores, verdicts or rewrites of the writer's work.** [AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md) sets the stance and the "May" list. This page is the flow: how each permitted kind of help appears, is accepted, is refused and is undone.

### What runs today, said plainly

- **There is no generative model in the app.** Nothing in a project is written, rewritten, summarised or scored by a language model.
- **Rule-based guesses on the device:** the breakdown's *The script mentions*; the calendar's quick add, which parses "Table read with Meera next Tue 7pm–9pm Sc 4, 7" without a cloud call; screenplay search that reads "mira night exteriors"; phonetic typing for seven Indian scripts.
- **One handoff that exists:** **Copy for AI** on a character page, "A guided handoff to your own AI chat."
- **One opt-in that sends text out** (Decision 0046): *Smart phonetic suggestions*, off by default, sending only the word being typed to an input service.
- **Agreed, not built:** the AI storyboard pack, exported for a tool the person chooses.

Never describe more than this as existing.

### The seven kinds of help, and how each behaves

| May | In Kwark | The flow |
|---|---|---|
| Measure | Runtime per scene, talk against action on the timeline | Shown as a fact, never a rating; same calm colours as everything else |
| Find | *The script mentions* in the breakdown | Offered one item at a time with its source and reason; **Add** or **Not needed** |
| Carry into production | Scenes into strips, cast into the call sheet | Automatic, because it is the writer's own data moving to where production reads it |
| Move the writer's words | An outline beat title proposed as a scene heading (pattern, not built) | Marked with a revision mark until accepted or edited |
| Convert typing | "naan ingey irukken" typed in Roman becomes Tamil | The Roman word shows under the caret; Space writes it in; Esc keeps it Roman, and that choice is remembered |
| Read aloud | Table reads with the browser's voices | A performance of the text as written |
| Hand off | Copy for AI; the storyboard pack | The person sees what travels, copies it, and pastes it where they choose |

### Find: suggestions the person accepts one by one

The breakdown's suggestion list is the model for anything a machine finds. Build it with the [suggestion panel](https://kwark.space/designSystem/components/suggestion-panel.md):

1. **A heading that names the source:** "The script mentions".
2. **A line that says nothing has happened:** "Read off the page, never assumed. Nothing here counts until you say so."
3. **Each item** with its category, its words from the page, and a reason a person can disagree with: "Set in capitals, the way an element is introduced." "Anything an actor handles has to be there on the day."
4. **Implied items** (somebody writes, so there is something to write with) are labelled as inferred and offered with a name to change.
5. **Add** and **Not needed** on each. A dismissal is kept, so the same item is not offered again.
6. A neutral count: "Suggestions waiting". Never "missed" or "ignored".

There is no **Accept all** for anything that reaches the script. A batch the person asked for (making twelve calendar dates from one sentence) is allowed, and its toast says each item can be changed: "12 dates added. Each can be changed or removed."

### Move the writer's words: the revision mark

When a machine proposes words in the work itself, they carry a [revision mark](https://kwark.space/designSystem/components/revision-mark.md): a soft tint, a dotted rule and an asterisk in the right margin, with a [provenance label](https://kwark.space/designSystem/components/provenance-label.md) that names the source, such as "* Suggested · from your outline, Act 2", and the line it came from. Buttons name the result: **Use heading**, **Edit**, **Not needed**.

- Accepted: the tint and star go; history keeps where it came from.
- Edited: the words are the person's. No mark.
- Dismissed: gone, and not offered again.
- Undone: one step.

The star is the film industry's own mark for a changed line; it prints, it is flat, and it disappears the moment a person makes the words theirs.

### Ask in your own words: the prompt input

Where Kwark accepts a sentence (the calendar's quick add, screenplay search), use the [prompt input](https://kwark.space/designSystem/components/prompt-input.md). It works like this:

- A label that says what it does ("Add to the calendar", "Search the screenplay") and an example of how to ask, not a chat persona.
- Parsed on the device. Nothing is sent anywhere.
- A preview of exactly what will be made before anything is made: the date, time, people and scenes read from the sentence, each editable.
- One action to make it, named with the result ("Add table read"), and Undo after.

It is a form that understands sentences, not a conversation, and it never writes into the screenplay.

### Hand off: Copy for AI

The character page's **Copy for AI** is how Kwark meets the AI tools people already use, without becoming one:

- **Choose what travels:** presets (Essentials, Full character, Actor preparation, Relationship, Custom selection), with "Include individual relationships & notes" as a separate choice. Only the chosen fields are projected into the prompt; whole records are never serialised.
- **Say what is and is not happening:** "Kwark prepares the prompt on your device. You decide where to paste it and what to share with that service. There is no AI chat or automatic sending here." Status: "Ready to copy. Nothing has been sent to an AI service."
- **Three steps:** Copy the prompt; Open a new AI chat; Paste, send, choose a mode.
- **The prompt protects the work:** it tells the other AI that the character material is reference, not instructions; to use only supplied facts; not to invent history as established; and never to claim that agreement there changes the record in Kwark. Its first reply is only a menu of modes, then it waits.
- **Fallbacks in words:** "Your browser could not copy automatically…", **Download JSON** with "JSON download started. Open the file and copy its contents into your AI chat."

What the person does in their own AI chat is their choice. Kwark's prompt never asks that AI to score or grade the writing.

The AI storyboard pack, when built, follows the same shape for a scene: a PDF, a zip of images and a master prompt; the prompt asks for character and location references first; the person uploads results back onto the panels, marked "Imported image" until edited. No generation on Kwark's servers, which would also break the free-tier budget.

### Multi-step machine actions: plan, activity, stop

Nothing in Kwark today runs a multi-step machine task on the work. If one is ever built (for example, proposing a breakdown for a whole act), it must:

- **Show the plan first** with the [agent plan](https://kwark.space/designSystem/components/agent-plan.md): the steps, what each reads and what each would change, in a list the person approves.
- **Show activity while it runs** with [agent activity](https://kwark.space/designSystem/components/agent-activity.md), step by step, with a **Stop** that works at once and keeps what is done.
- **End in a review**, not an apply, with the [AI result review](https://kwark.space/designSystem/components/ai-review.md): every proposed change listed with its source, accepted one by one, with dismissals kept.
- **Be one Undo** away, as a single [undo entry](https://kwark.space/designSystem/components/ai-undo-entry.md) in the history named for what it did ("Undo: 14 breakdown items from Act 2").

## Anatomy

| Part | Means | Rule |
|---|---|---|
| Source heading | Where the material came from | Words, never a sparkle: "The script mentions", "from your outline" |
| Reason line | Why this was offered | A plain sentence, never a confidence percentage |
| Status line | That nothing has happened yet | "Nothing here counts until you say so." |
| Per-item actions | Accept or refuse this one | **Add** / **Not needed**, **Use heading** / **Edit** / **Not needed** |
| Revision mark | Proposed words in the work | Tint, dotted rule, margin star, until a person accepts or edits |
| Provenance label | The mark's words | "* Suggested · from your outline, Act 2" |
| Consent line | What leaves the device and to whom | Before anything is sent; off by default; per project |
| Undo entry | The reversal | One step, named for what it undoes |

## Rules

- **Never** score, grade, rate, critique, rank, compare or rewrite a person's writing, or show any percentage that rates it (Decision 0002).
- **Never** write machine-proposed words or items into the work without a person accepting each one.
- **Never** offer Accept all for anything that reaches the script.
- **Never** mark machine help with sparkles, glows, gradients, purple, or an "AI" badge. Say the source in words.
- **Never** show confidence scores. A guess is labelled a guess.
- **Never** complete the writer's sentence as ghost text; Tab belongs to the screenplay.
- **Never** send a person's work to an outside service unless they turned it on for that project, knowing what is sent and to whom; and never for a student until guardian consent exists.
- **Must** give every suggestion its source, a reason, and a refusal that sticks.
- **Must** make every machine action undoable in one step.
- **Must** ask with the [AI consent prompt](https://kwark.space/designSystem/components/ai-consent.md) before anything leaves the device, and label every handoff with what is and is not sent: "Nothing has been sent to an AI service."
- **Always** run guesses on the device when possible; a cloud call costs the free tier and the person's privacy.
- **Always** say plainly what exists today; never claim a model, feature or protection that does not.

## Edge cases

- **The page changes after a suggestion.** If the words it came from are gone, the suggestion goes too; it never points at text that no longer exists.
- **Two editors.** A suggestion accepted by one person is accepted for the project; a dismissal by one is a dismissal for all, and the history says who.
- **Read-only people** see no suggestions; there is nothing they could accept.
- **Indian scripts.** Suggestions read the script as written; phonetic conversion never runs on words the writer chose to keep Roman.
- **A pasted prompt-like text inside a character note.** The handoff treats it as reference material, never as instructions.
- **Offline.** On-device guesses work; anything that would send text out says it cannot run and does nothing else.

## Phone and desktop

On desktop, suggestions sit in the panel beside the page they came from, and a revision mark's actions sit under the marked line. On a phone, suggestions are a sheet opened from Menu ("The script mentions"), each item a 44px row with Add and Not needed; the revision label and its actions sit directly under the line, never in a hover. The handoff dialog is a full-screen sheet with the three steps in order.

## Writing

- Name the source: "The script mentions", "from your outline", "Imported image".
- Say nothing has happened yet: "Nothing here counts until you say so." "Ready to copy. Nothing has been sent to an AI service."
- Name refusals plainly: **Not needed**, never "Reject" or "Ignore".
- Never "AI-powered", "magic", "smart" as a selling word, or "Let AI…". *Smart phonetic suggestions* names one setting and says what it costs.

## Accessibility

- A revision mark's label is linked to the marked text with `aria-describedby`, so a screen reader hears "Suggested, from your outline, Act 2" with the words.
- Suggestions are a list; each item's actions include the item in their names ("Add Reel 3", "Reel 3 not needed").
- The tint is never the only signal: the margin star and the label carry the meaning, and both print.
- Status lines ("Nothing has been sent…") are visible text, not tooltips.

**Do:** Offer **Reel 3** under "The script mentions", with its reason and **Add** or **Not needed**.

**Don't:** Fill the breakdown with 40 items and toast "AI found 40 props" with a sparkle.

**Do:** "* Suggested · from your outline, Act 2" beside a tinted heading, with **Use heading**, **Edit**, **Not needed**.

**Don't:** "Here is a stronger version of Mira's line" with a rewritten speech and a score of 82%.

**Do:** Copy for AI: choose what travels, "Nothing has been sent to an AI service.", then paste it in the chat the person picks.

**Don't:** A chat sidebar inside the screenplay that edits the script as it talks.

## Demo

```html
<div style="display:grid;gap:10px;max-width:480px;width:100%">
<p class="kw-rev-line" style="font:400 var(--k-fs-body)/1.7 var(--k-font-screenplay);margin:0" aria-describedby="ai-rev-src">INT. <span class="kw-rev">EDIT SUITE – NIGHT</span></p>
<span class="kw-rev-label" id="ai-rev-src">* Suggested · from your outline, Act 2</span>
<p class="kw-hint" style="margin:0">From the beat "Mira finds the splice in the edit suite, night."</p>
<div style="display:flex;gap:8px;flex-wrap:wrap"><button class="kw-button kw-button--sm kw-button--primary" type="button">Use heading</button><button class="kw-button kw-button--sm" type="button">Edit</button><button class="kw-button kw-button--sm kw-button--quiet" type="button">Not needed</button></div>
</div>
<div class="kw-card" style="width:100%;max-width:480px;display:grid;gap:10px">
<label class="kw-field"><span class="kw-label">Add to the calendar</span><input class="kw-input" value="Table read with Meera next Tue 7pm–9pm Sc 4, 7"></label>
<dl style="margin:0;display:grid;grid-template-columns:auto 1fr;gap:4px 12px"><dt class="kw-row__meta">What</dt><dd style="margin:0">Table read</dd><dt class="kw-row__meta">When</dt><dd style="margin:0">Next Tuesday · 19:00–21:00</dd><dt class="kw-row__meta">Who</dt><dd style="margin:0">Meera</dd><dt class="kw-row__meta">Scenes</dt><dd style="margin:0">4, 7</dd></dl>
<span class="kw-hint">Read on this device. Nothing is sent anywhere.</span>
<span><button class="kw-button kw-button--primary" type="button">Add table read</button></span>
</div>
<div class="kw-card" style="width:100%;max-width:480px;display:grid;gap:10px">
<strong>Copy for AI</strong>
<div class="kw-segment" role="group" aria-label="Context presets"><button type="button" aria-pressed="true">Essentials</button><button type="button" aria-pressed="false">Full character</button><button type="button" aria-pressed="false">Actor preparation</button></div>
<span class="kw-hint">Kwark prepares the prompt on your device. You decide where to paste it and what to share with that service. There is no AI chat or automatic sending here.</span>
<div style="display:flex;gap:8px;align-items:center;flex-wrap:wrap"><button class="kw-button kw-button--primary" type="button">Copy prompt</button><button class="kw-button kw-button--quiet" type="button">Download JSON</button><span class="kw-row__meta" role="status">Ready to copy. Nothing has been sent to an AI service.</span></div>
</div>
<div class="kw-toast kw-toast--info" role="status"><span>12 dates added. Each can be changed or removed.</span><button class="kw-text-button" type="button">Undo</button></div>
```

## Related

[AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md), [Revision mark](https://kwark.space/designSystem/components/revision-mark.md), [Suggestion panel](https://kwark.space/designSystem/components/suggestion-panel.md), [Provenance label](https://kwark.space/designSystem/components/provenance-label.md), [AI consent prompt](https://kwark.space/designSystem/components/ai-consent.md), [Prompt input](https://kwark.space/designSystem/components/prompt-input.md), [Agent plan](https://kwark.space/designSystem/components/agent-plan.md), [Agent activity](https://kwark.space/designSystem/components/agent-activity.md), [AI result review](https://kwark.space/designSystem/components/ai-review.md), [AI undo history](https://kwark.space/designSystem/components/ai-undo-entry.md), [Toast](https://kwark.space/designSystem/components/toast.md), [Search and filter](https://kwark.space/designSystem/patterns/search-and-filter.md), [Print and export](https://kwark.space/designSystem/patterns/print-and-export.md), [Structure, not teaching](https://kwark.space/designSystem/method/structure-not-teaching.md).

## AI readiness test

**Task:** Offer filming locations for the Locations list from the screenplay of Blank Pages.

**Give the agent:** This page, AI and authorship, Revision mark, Decisions 0002, 0004, 0005.

**Constraint:** On the device; nothing added until the person agrees; no judgement.

**A reliable answer:**
- Each location offered with the scene heading it came from and a plain reason
- Add and Not needed per item, dismissals remembered, no Accept all
- A neutral count and "Nothing here counts until you say so."
- No sparkles, confidence scores or AI badges
- One Undo for each addition
- nothing sent off the device
