@troylar/flightdeck 1.10.0 → 1.11.1

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 <!-- Generated by build.py from src/releases.json. Edit that file, not this one. -->
 
+## 1.11.1 · Oct 18, 2026
+
+Checklist versions this copy can't read are never run.
+
+### Fixed
+
+- **Versions this copy doesn't understand can't be started** (Runs). Such a version isn't offered to start, plan or pick. The process page and the version picker say why: update Flightdeck to run it. A plan made for it starts on the latest version you can run, and says so. A run started on it, or saved by a newer copy with details or a file format this copy doesn't know, opens read-only with the reason, and this copy never saves over it or plans another like it. *Where:* A process page, the version picker, Start a run, and the run page.
+
+## 1.11.0 · Oct 18, 2026
+
+Planned runs, a flight plan view, a checklist builder, and organized step types.
+
+### New
+
+- **Suggest a fix to the checklist** (Runs). Anyone in a run can suggest a fix to the checklist from a step, a phase or a screenshot: a missing step, wrong instructions, a bad screenshot (attach the right one), wrong order, wrong role, or something else. On the process page, anyone can accept or decline each one with a reason. Accepted ones show as fixed once a newer version is published. Copy fix brief hands them to your AI assistant. *Where:* A run: Suggest a fix on a step or phase. A process page: Suggested fixes.
+- **See a process as a flight plan** (Processes). On a process page, switch the checklist to Flight plan to see its shape at a glance: phases from start to landing, gates as checkpoints, tracks side by side and linked processes. With runs of that version, it shows each phase's usual time and the step that most often goes off-script. It marks steps covered by skills built from that version. Choose a phase to go to it. *Where:* A process page, the Checklist | Flight plan switch.
+- **Edit a checklist with the builder** (Processes). Edit a draft as an outline: phases as cards, steps as rows, gates as striped bars. Drag a step, or select it and press Alt+Up or Alt+Down, to move it. Change a step's text, type, roles, run details and fields in the side form, and add steps, phases and gates. It writes the same Markdown, changing only the lines you touched and never a step ID. Markdown is one click away. *Where:* A process page: Edit, then the Builder | Markdown switch.
+- **Plan a run ahead of time** (Runs). Plan a run in the app: a name, the details you know, who does what and an optional time. Planned runs are listed by time under Runs and show on Home from a day before. Nothing starts until someone starts it. *Where:* A process page: Plan a run.
+- **Plan another like this** (Runs). Duplicate any run into a new plan with its details and roles. Its answers, notes and gates are never copied, and details a step fills in during the run are left for the new run. *Where:* A run, or its receipt: Plan another like this.
+- **Plans keep their version** (Runs). A plan starts on the version it was planned on. If a newer one is published first, the plan says so, shows what changed and switches with one click. *Where:* Starting a planned run.
+
+### Improved
+
+- **Step types in groups, with tags** (Step types). Step types are listed in groups, like processes and skills, with a tag filter. Give a team type a group and tags in its form; built-ins are grouped as General, Tools and Automation. Reorganizing a type never marks a process or a skill as changed. *Where:* Step types.
+
+### Fixed
+
+- **Clearer while a step type saves** (Step types). While Keep mine saves, the conflict shows Saving… instead of buttons that would do nothing, and Cancel and Discard my changes leave keyboard focus somewhere useful. *Where:* Step types, and the draft editor.
+
 ## 1.10.0 · Oct 18, 2026
 
 Clear sections, and templates and step types you manage in the app.

package/README.md

@@ -20,13 +20,29 @@ Every team has processes that live in someone's head: the release, the check-in,
 
 It's **one HTML file**. No server, no sign-in, no network, no AI inside. It works offline in Edge or Chrome and keeps everything in a folder your team already shares.
 
-<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/run-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/run-light.png" alt="A release in progress: run details including a release tag set by an earlier step, roles, phases on the left with their gates, the current phase, and step notes on the right" width="1000"></picture></p>
+<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/run-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/run-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/run-light.png" alt="A release in progress: run details including a release tag set by an earlier step, roles, phases on the left with their gates, the current phase, and step notes on the right" width="1000"></picture></a></p>
+
+<br>
+
+## Your skills, tied to the process they automate
+
+Teams are turning runbooks into AI skills fast. Then the process changes, and nobody can say which skills are now wrong.
+
+Flightdeck keeps that link, version by version:
+
+- **Built from proof.** Prove a version with three clean runs and its owner's sign-off, then brief your AI assistant to build the skill.
+- **Traced to the step.** Each registered skill links to an exact process version and the steps it covers (or the whole process), plus where its source lives.
+- **Changes flagged.** Publish a new version and Flightdeck shows which registered skills follow steps that changed, and which are still current.
+- **Fixes, briefed.** One click copies an update brief: the before and after of each changed step, and the process as it is now.
+- **Evidence kept.** Every run keeps who checked each step, what was marked N/A, and where people did it differently.
+
+<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/skills-traced-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skills-traced-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skills-traced-light.png" alt="A process goes from v1 to v2 and one step changes. Flightdeck checks the registered skills: release-deploy and release-notes need an update, pr-opener is current. The update brief for release-deploy shows the exact before and after for your AI assistant." width="1000"></picture></a></p>
 
 <br>
 
 ## The loop
 
-<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/loop-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/loop-light.png" alt="Write a checklist, publish a frozen version, run it, prove it with three clean runs and the owner sign-off, then your AI assistant builds the skill from the brief. A step done differently becomes a suggested checklist change; a new version that changes a covered step marks the skill as needing an update." width="1000"></picture></p>
+<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/loop-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/loop-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/loop-light.png" alt="Write a checklist, publish a frozen version, run it, prove it with three clean runs and the owner sign-off, then your AI assistant builds the skill from the brief. A step done differently becomes a suggested checklist change; a new version that changes a covered step marks the skill as needing an update." width="1000"></picture></a></p>
 
 Flightdeck keeps checklists and run records together, links to skills stored elsewhere, and flags process changes that affect them.
 
@@ -58,14 +74,14 @@ Then open `flightdeck.html` from the team folder, go to **Settings → Open team
 
 **Home** shows only what needs you, each with one button: the run you're recording, a plan to review, a skill to update.
 
-<picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/home-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/home-light.png" alt="Home: three things that need you, each with one button, and counts of runs, processes, skills and step types"></picture>
+<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/home-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/home-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/home-light.png" alt="Home: three things that need you, each with one button, and counts of runs, processes, skills and step types"></picture></a>
 
 </td>
 <td width="50%" valign="top">
 
 **Processes** are your templates, in your team's own hierarchy and tags. **New process** starts one.
 
-<picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/processes-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/processes-light.png" alt="Processes: the team templates grouped by hierarchy, with tags, skill counts and last run"></picture>
+<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/processes-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/processes-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/processes-light.png" alt="Processes: the team templates grouped by hierarchy, with tags, skill counts and last run"></picture></a>
 
 </td>
 </tr>
@@ -74,14 +90,14 @@ Then open `flightdeck.html` from the team folder, go to **Settings → Open team
 
 **A process** is one page: its checklist with skill badges, whether it's ready for a skill, its skills, versions and recent runs.
 
-<picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/process-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/process-light.png" alt="The Production release process: the v2 checklist, Ready for a skill, two skills marked needs update, versions and recent runs"></picture>
+<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/process-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/process-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/process-light.png" alt="The Production release process: the v2 checklist, Ready for a skill, two skills marked needs update, versions and recent runs"></picture></a>
 
 </td>
 <td valign="top">
 
-**Edit** in place: the Markdown beside a live check and preview. If the draft changed since you opened it, you see both and choose.
+**Edit** in place, as an outline or as Markdown, beside a live check and preview. If the draft changed since you opened it, you see both and choose.
 
-<picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/edit-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/edit-light.png" alt="Editing a draft: the Markdown on the left, Ready to publish and a live preview on the right"></picture>
+<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/edit-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/edit-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/edit-light.png" alt="Editing a draft: the Markdown on the left, Ready to publish and a live preview on the right"></picture></a>
 
 </td>
 </tr>
@@ -90,14 +106,62 @@ Then open `flightdeck.html` from the team folder, go to **Settings → Open team
 
 **Skills**: every skill built from your processes, wherever it lives, and which ones need an update.
 
-<picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skills-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skills-light.png" alt="Skills: two skills that need an update, then every skill in the team hierarchy with tag filters"></picture>
+<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/skills-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skills-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skills-light.png" alt="Skills: two skills that need an update, then every skill in the team hierarchy with tag filters"></picture></a>
+
+</td>
+<td valign="top">
+
+**A skill** says what changed under it and gives your AI assistant the exact before and after.
+
+<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/skill-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skill-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skill-light.png" alt="The release-deploy skill: needs an update because one of its steps changed in v2, with a Copy the update brief button and where the skill lives"></picture></a>
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+**Flight plan** shows a version's shape: phases from start to landing, gates as checkpoints, tracks side by side, and, from that version's runs, typical times, autopilot (steps skills cover) and turbulence.
+
+<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/flight-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/flight-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/flight-light.png" alt="The release v1 as a flight plan: Start, three phases with typical times, gates as striped checkpoints, a connecting flight to Check in code, autopilot and turbulence notes, and two parallel tracks"></picture></a>
 
 </td>
 <td valign="top">
 
-**A skill** says what changed under it and gives your LLM the exact before and after.
+The **Builder** edits a draft as an outline: drag a step or press Alt+Up / Alt+Down, change it in the side form, and **Undo**. It writes the same Markdown.
 
-<picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skill-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skill-light.png" alt="The release-deploy skill: needs an update because one of its steps changed in v2, with a Copy the update brief button and where the skill lives"></picture>
+<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/builder-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/builder-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/builder-light.png" alt="The outline builder: phases as cards with steps as rows and a striped gate bar; the selected step's side form with its text, kind, type, roles, run details and fields"></picture></a>
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+**Runs**: what's running, what's **planned** (by a person or your AI assistant) and what finished.
+
+<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/runs-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/runs-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/runs-light.png" alt="Runs: one release running, two planned releases (one by Casey Nguyen with a time, one by an AI assistant), and finished runs"></picture></a>
+
+</td>
+<td valign="top">
+
+**Plan a run** for later: the details you know, who does what, and an optional time. Nothing starts until someone starts it.
+
+<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/plan-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/plan-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/plan-light.png" alt="Plan a run: run name, ticket and environment filled in, a time and a note, and suggested people for each role"></picture></a>
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+**Suggest a fix** from any step or phase during a run: what's wrong, and what it should say.
+
+<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/fix-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/fix-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/fix-light.png" alt="Suggest a fix to a step during a run: the instructions are wrong, with the text it should say"></picture></a>
+
+</td>
+<td valign="top">
+
+**Suggested fixes** on the process page: accept or decline each one, see which are fixed in a newer version, and copy a fix brief for your AI assistant.
+
+<a href="https://github.com/troylar/flightdeck/blob/main/docs/images/fixes-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/fixes-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/fixes-light.png" alt="Suggested fixes on the process page: one declined with a reason, one fixed in v2, one open with Accept into the draft and Decline, one in the draft"></picture></a>
 
 </td>
 </tr>
@@ -107,6 +171,11 @@ Then open `flightdeck.html` from the team folder, go to **Settings → Open team
 
 ## What it does
 
+<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/features-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/features-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/features-light.png" alt="Eight features: gates that approve exactly what they say; one recorder with everyone watching; typed steps for Jenkins, Bitbucket, Jira and commands; real Jira workflows with required fields; clock times, deadlines, tracks and pauses; linked runs of other processes; run details that flow to later steps; and insights from every run." width="1000"></picture></a></p>
+
+<details>
+<summary><b>Every feature, in detail</b></summary>
+
 <table>
 <tr>
 <td width="50%" valign="top">
@@ -118,7 +187,7 @@ Every phase ends at a **gate**. Nothing after it opens until someone passes it,
 <td width="50%" valign="top">
 
 ### One recorder, everyone watching
-One person records; everyone else follows on their own screen and adds notes and screenshots to any step. Hand recording over, or pick it up from another window. Two computers saving at once never overwrite each other: the loser becomes a copy you can compare and keep.
+One person records; everyone else follows on their own screen and adds notes and screenshots to any step. Hand recording over, or pick it up from another window. Every save first checks the file hasn't changed; if it has, yours is kept next to it as a copy you can compare and keep. Where two computers can't take turns, a save that gets replaced is still kept as a receipt and shown as a copy, so nothing is silently lost.
 
 </td>
 </tr>
@@ -160,17 +229,19 @@ A step can **set** a run detail: the merge step records the release tag, and eve
 <td valign="top">
 
 ### Runs that teach the checklist
-Every "did it differently", every block, every re-check is kept. A process's **How runs go** shows typical time per phase, the steps that go off-script most, and who has never held which role yet, so the next rotation is obvious.
+Every "did it differently", every block, every re-check is kept. Anyone in a run can **suggest a fix** to the checklist from a step, a phase or a screenshot; the team accepts or declines it on the process page, and one click copies a fix brief for your AI assistant. A process's **How runs go** shows typical time per phase, the steps that go off-script most, and who has never held which role yet, so the next rotation is obvious.
 
 </td>
 </tr>
 </table>
 
+</details>
+
 <br>
 
 ## A checklist, in twenty lines
 
-Checklists are Markdown. Your LLM writes them; people publish them.
+Checklists are Markdown. Your AI assistant writes them; people edit and publish them, in the builder or as Markdown.
 
 ```markdown
 ---
@@ -219,13 +290,17 @@ Publishing freezes a checklist as a numbered version, with who, when and why. Ru
 A process is one page, with its checklist in the middle:
 
 - **Read it** the way a run shows it, or switch on **Markdown** to see and copy the source.
-- **Edit** it in place: the Markdown beside a live check (what blocks publishing, and what's just a tip) and a preview, updated as you type. **Done** takes you back; **Publish** appears when the draft has changes.
+- **See its shape** with **Flight plan**: phases as waypoints from start to landing, gates as checkpoints, tracks as parallel lanes, linked processes as connecting flights, and, from that version's own runs and skills, typical times, the steps covered by skills (autopilot) and the steps that go off-script most (turbulence). Choose a phase to jump to it in the checklist.
+- **Edit** it in place: the **Builder** (phases as cards, steps as rows, gates as striped bars; drag a step or press Alt+Up / Alt+Down to move it, and change a step's text, type, roles, run details and fields in its side form; **Undo** steps back through builder changes) or the **Markdown**, beside a live check (what blocks publishing, and what's just a tip) and a preview. Both edit the same Markdown: the builder changes only the lines you touch and never a step ID, and keeps comments and lines it doesn't understand. **Done** takes you back; **Publish** appears when the draft has changes.
 - **Look back**: pick any version from the version list or the Versions panel. An older version shows with a way back to the current one and **Restore as draft**.
+- **Versions this copy can't use** are listed with the reason instead: still syncing, damaged, or written by a newer Flightdeck ("update Flightdeck to run it"). They can't be started, planned or picked, and a run started on one by a newer copy opens read-only, so this copy never saves over it.
 - **How runs go**: typical time per phase, the steps that go off-script most, and who has held each role.
 
 Beside the checklist: whether it's ready for a skill, its skills, its versions and its recent runs.
 
-Saving is careful. A save only goes through if the draft is still exactly what you opened. If a teammate or your LLM changed it meanwhile, nothing is saved: you see their version and choose to keep yours or take theirs. One limit: a shared folder can't lock a file, so a change that lands in the instant between that check and the write can still be replaced. Edit a draft with one person (or one LLM) at a time. Saving never publishes; publishing is a separate, logged step.
+**Plan a run** for later, next to **Start a run**: a name, the details you know, who does what and an optional time. **Plan another like this** on any run or receipt copies its details and roles, never its answers. Planned runs are listed by time under **Runs** and show on Home when they're due; a plan starts on the version it was planned on until you switch to the newer one.
+
+Saving is careful. A save only goes through if the draft is still exactly what you opened. If a teammate or your AI assistant changed it meanwhile, nothing is saved: you see their version and choose to keep yours or take theirs. One limit: a shared folder can't lock a file, so a change that lands in the instant between that check and the write can still be replaced. Edit a draft with one person (or one AI assistant) at a time. Saving never publishes; publishing is a separate, logged step.
 
 **New process** on the Processes page asks for an ID, title, group, tags, run details, roles and owner, starts the draft, and opens it in the editor.
 
@@ -233,15 +308,15 @@ Saving is careful. A save only goes through if the draft is still exactly what y
 
 ## Your own step types
 
-Built-in types cover common tools. When your team has its own kind of step (a change request, a security sign-off), make it a type:
+Built-in types cover common tools, grouped as General, Tools and Automation, with your team's types in their own groups and a tag filter. When your team has its own kind of step (a change request, a security sign-off), make it a type:
 
 1. **Step types → New step type**, or **Copy to a team type** on any built-in.
-2. Add rows for its **fields** (what a checklist can say about the step) and its **evidence** (what's recorded when it's checked). The form checks it as you go and shows the checklist line and the file it will save.
+2. Give it a **group** and **tags** if you like (they only organize the list), then add rows for its **fields** (what a checklist can say about the step) and its **evidence** (what's recorded when it's checked). The form checks it as you go and shows the checklist line and the file it will save.
 3. **Save step type** writes `step-types/<id>.json`. Checklists can use `{your.type}` right away; publishing freezes it into each version, so editing it later never changes an old one.
 
 Or describe it to your AI assistant: `/flightdeck-new-step-type a change request the CAB approves, with the change number as evidence`.
 
-<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/types-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/types-light.png" alt="Step types: your team types, then each built-in type with what it is for, how many checklists use it, and a button to copy it to a team type" width="1000"></picture></p>
+<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/types-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/types-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/types-light.png" alt="Step types: your team types, then each built-in type with what it is for, how many checklists use it, and a button to copy it to a team type" width="1000"></picture></a></p>
 
 <br>
 
@@ -249,11 +324,16 @@ Or describe it to your AI assistant: `/flightdeck-new-step-type a change request
 
 This is what Flightdeck is for. Outside the team it's usually called **SOP-to-skill**: turning a standard operating procedure into an agent skill. Flightdeck adds the part that's usually missing: **traceability**. Each registered skill links to the exact process version and steps it follows, and runs are the evidence. Flightdeck flags process changes that affect a skill; it doesn't detect changes to the skill itself.
 
+<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/trace-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/trace-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/trace-light.png" alt="Five steps from process to skill: prove it with 3 clean runs, the owner signs it off, copy the brief, register the skill with its source and the steps it follows, and stay in step as new versions flag the skills they affect. Skill statuses: current, note version, needs an update, check it." width="1000"></picture></a></p>
+
+<details>
+<summary><b>How it works, step by step</b></summary>
+
 **1. Prove a version.** Each process page shows its run evidence. A run counts as clean only when it ended Completed, every covered step was done, every gate on that work (and the one before it) was passed, and nothing was blocked, re-checked, marked N/A or done differently, even in answers since archived.
 
 **2. Sign off.** With three clean runs, the process owner signs the version off. Only the owner's sign-off counts, and only for that exact published version.
 
-**3. Brief your LLM.** One click copies a brief with the process in order: phases and their mode, tracks, every step with its fields, evidence and screenshots, every gate with what it approves, the run details it receives, and what people actually did differently.
+**3. Brief your AI assistant.** One click copies a brief with the process in order: phases and their mode, tracks, every step with its fields, evidence and screenshots, every gate with what it approves, the run details it receives, and what people actually did differently.
 
 **4. Register the skill.** It can live anywhere: a repo, a shared folder, a local path. Its `location` is the skill's source path or link:
 
@@ -277,12 +357,14 @@ Leave out `steps` for a skill that covers the whole process. A process can have
 |---|---|---|
 | **current** | Built from the version in use | Nothing |
 | **note version** | The process changed, but none of this skill's steps did | Move its `implements` forward |
-| **needs update** | Its steps, their order, their gates, their step types, screenshots or run details changed | Copy the update brief: the exact before and after, for your LLM |
+| **needs update** | Its steps, their order, their gates, their step types, screenshots or run details changed | Copy the update brief: the exact before and after, for your AI assistant |
 | **check it** | It can't be matched: a missing version, a clash, or an unreadable file | Fix the registration |
 
-The same rules are in the `flightdeck-skill-brief` skill for your AI assistant, so a brief from your LLM and a brief from the app agree.
+The same rules are in the `flightdeck-skill-brief` skill for your AI assistant, so a brief your AI assistant writes and a brief from the app agree.
 
-<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skill-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skill-light.png" alt="A skill that needs an update: the step that changed and the button that copies the update brief" width="1000"></picture></p>
+</details>
+
+<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/skill-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skill-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/skill-light.png" alt="A skill that needs an update: the step that changed and the button that copies the update brief" width="1000"></picture></a></p>
 
 <br>
 
@@ -301,6 +383,11 @@ The same rules are in the `flightdeck-skill-brief` skill for your AI assistant,
 
 ## The team folder
 
+<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/folder-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/folder-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/folder-light.png" alt="The team folder and who writes each part: people.json and validations by people; drafts and step types by people and your AI assistant; skills, Jira workflows and proposals by your AI assistant; publications and runs by Flightdeck." width="1000"></picture></a></p>
+
+<details>
+<summary><b>The folder, as text</b></summary>
+
 ```
 people.json            who's on the team
 maps/drafts/           checklists being written (Markdown)
@@ -308,15 +395,18 @@ publications/          published versions, frozen (Flightdeck writes these)
 runs/                  one folder per run: run.json, everyone's notes, screenshots
 skills/                skill registrations: each skill's source, what it implements
 validations/           owners' sign-offs that a version is ready for a skill
+suggestions/           decisions on suggested fixes (accepted, declined, reopened), one file per person's window
 step-types/            your team's own step types (create them in the app)
 jira/workflows.json    your real Jira workflows, with required fields
-proposals/             runs your LLM planned, waiting for a person to start them
+proposals/             planned runs (from the app or your AI assistant), waiting for a person to start them
 images/                screenshots that checklists refer to
 AGENTS.md              the rules any AI assistant follows in this folder
 .flightdeck/skills/    the Flightdeck skills for your AI assistant
 ```
 
-Every file has exactly one writer, so a shared folder never corrupts. Your LLM writes checklists, plans, step types, workflows and skill registrations; people publish, run and sign off.
+</details>
+
+Every file has exactly one writer, which keeps ordinary use of a shared folder free of conflicts; when two saves do collide, the replaced one is kept for you to recover. Your AI assistant writes checklists, plans, step types, workflows and skill registrations; people publish, plan, run and sign off.
 
 <br>
 
@@ -339,13 +429,20 @@ Every file has exactly one writer, so a shared folder never corrupts. Your LLM w
 
 ## Safe by design
 
+<p align="center"><a href="https://github.com/troylar/flightdeck/blob/main/docs/images/safe-light.png" title="Open in GitHub's image viewer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/safe-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/safe-light.png" alt="Safe by design: nothing leaves your machine; no server or accounts; saves that check first; built for OneDrive; a careful command; accessible." width="1000"></picture></a></p>
+
+<details>
+<summary><b>The details</b></summary>
+
 - **Nothing leaves your machine.** The app makes no network requests and loads nothing from the internet; its fonts and code are inside the file.
 - **No server to run, no accounts to manage.** Your data is files in a folder you already control.
-- **One writer per file, and checked saves.** Two computers saving a run at once never overwrite each other: the loser becomes a copy you compare and keep. Drafts and step types are saved only over the version you opened; a change that lands in the instant between that check and the write is the one case a shared folder can't catch, so edit them one at a time.
+- **One writer per file, and checked saves.** A run is saved only if its file hasn't changed since this window read it; otherwise this window's version is kept beside it as a copy to compare and keep. Two computers that can't see each other's changes yet can still both write, so every save first leaves its own receipt: one that gets replaced shows up in the run as a copy, never silently lost (see [docs/onedrive.md](https://github.com/troylar/flightdeck/blob/main/docs/onedrive.md)). Drafts and step types are saved only over the version you opened; a change that lands in the instant between that check and the write is the one case a shared folder can't catch, so edit them one at a time.
 - **Built for OneDrive.** Folders that sync a minute late are expected; a gate means "passed for this commit, by this person," never a live lock.
 - **The command is careful too.** No dependencies, nothing runs on install, no network. It refuses to write through links, writes whole files atomically, and never replaces a newer version without `--force`.
 - **Accessible.** Every control has a label, errors sit next to their field, shortcuts can be turned off, and it works with a keyboard.
 
+</details>
+
 <br>
 
 ## Coming from Preflight
@@ -356,19 +453,61 @@ Flightdeck was called Preflight before 1.9.0. Team folders, runs and published v
 
 ## FAQ
 
-**Does Flightdeck run anything for me?** No. It never calls Jenkins, Bitbucket or Jira, and never runs a command. It shows the command to copy, records what happened, and keeps the clock. Your skills do the automating.
+<details>
+<summary><b>Does Flightdeck run anything for me?</b></summary>
+
+No. It never calls Jenkins, Bitbucket or Jira, and never runs a command. It shows the command to copy, records what happened, and keeps the clock. Your skills do the automating.
+
+</details>
+
+<details>
+<summary><b>Where does the AI live?</b></summary>
+
+Outside Flightdeck. Your AI assistant writes checklists and builds skills from Flightdeck's briefs. Flightdeck versions the checklists and records which process version each skill follows.
+
+</details>
+
+<details>
+<summary><b>Can a skill cover only part of a process?</b></summary>
+
+Yes. List its `steps`. The brief tells it which gate to wait for before its first step, and the evidence and status consider only those steps.
+
+</details>
+
+<details>
+<summary><b>Can a skill come first?</b></summary>
+
+Yes. Ask your AI assistant to draft a checklist from an existing skill, publish it, and register the skill against that process version; then run and prove the checklist as usual. If the skill changes first, update and publish the checklist, then update the registration. Flightdeck doesn't detect skill changes. A guided skill-first workflow and skill change detection are planned.
+
+</details>
+
+<details>
+<summary><b>Can people edit checklists in the app, or only the AI assistant?</b></summary>
+
+Both. The app's editor and your AI assistant write the same draft files. The app saves only over the version you opened and shows both when they differ; since a shared folder can't lock a file, edit a draft with one of them at a time.
+
+</details>
+
+<details>
+<summary><b>What if someone on the team has a newer Flightdeck?</b></summary>
+
+A version or run saved by a newer copy, with checklist features this copy doesn't understand, is shown with the reason and "Update Flightdeck to run it." It can't be started here, and a run on it opens read-only, so an older copy never records over what a newer one wrote. Put the newest `flightdeck.html` in the team folder; anyone on an older copy sees that a newer one is there.
+
+</details>
 
-**Where does the AI live?** Outside Flightdeck. Your AI assistant writes checklists and builds skills from Flightdeck's briefs. Flightdeck versions the checklists and records which process version each skill follows.
+<details>
+<summary><b>What's new in each version?</b></summary>
 
-**Can a skill cover only part of a process?** Yes. List its `steps`. The brief tells it which gate to wait for before its first step, and the evidence and status consider only those steps.
+The top bar shows the version and **What's new**, the full searchable history. It's also in [CHANGELOG.md](https://github.com/troylar/flightdeck/blob/main/CHANGELOG.md).
 
-**Can a skill come first?** Yes. Ask your AI assistant to draft a checklist from an existing skill, publish it, and register the skill against that process version; then run and prove the checklist as usual. If the skill changes first, update and publish the checklist, then update the registration. Flightdeck doesn't detect skill changes. A guided skill-first workflow and skill change detection are planned.
+</details>
 
-**Can people edit checklists in the app, or only the LLM?** Both. The app's editor and your LLM write the same draft files. The app saves only over the version you opened and shows both when they differ; since a shared folder can't lock a file, edit a draft with one of them at a time.
+<details>
+<summary><b>Where's the source?</b></summary>
 
-**What's new in each version?** The top bar shows the version and **What's new**, the full searchable history. It's also in [CHANGELOG.md](https://github.com/troylar/flightdeck/blob/main/CHANGELOG.md).
+[github.com/troylar/flightdeck](https://github.com/troylar/flightdeck). The design and its decisions are in [docs/design.md](https://github.com/troylar/flightdeck/blob/main/docs/design.md).
 
-**Where's the source?** [github.com/troylar/flightdeck](https://github.com/troylar/flightdeck). The design and its decisions are in [docs/design.md](https://github.com/troylar/flightdeck/blob/main/docs/design.md).
+</details>
 
 <br>