@troylar/flightdeck 1.10.0

package/CHANGELOG.md

@@ -0,0 +1,171 @@
+# Flightdeck release notes
+
+<!-- Generated by build.py from src/releases.json. Edit that file, not this one. -->
+
+## 1.10.0 · Oct 18, 2026
+
+Clear sections, and templates and step types you manage in the app.
+
+### New
+
+- **One page for each process: read, edit and version its checklist** (Processes). A process is one page with its checklist in the middle. Read it, show its Markdown to copy, or choose Edit to change the draft in place, checked and previewed as you type; saving stops and shows both if the draft changed since you opened it. Pick an older version to look back or restore it. How runs go has typical times and who has held each role. *Where:* Processes → a process.
+- **Start a new process** (Processes). New process asks for an ID, title, group, tags, run details, roles and owner, then starts a draft checklist in maps/drafts/ and opens it for editing. *Where:* Processes → New process.
+- **See every step type, and create your own** (Step types). Step types lists every built-in and team type: what it's for and how many checklists use it, with its fields and evidence one click away. New step type builds one from rows of fields and evidence, checked as you go, with the checklist line and the file it will save. Edit a team type, or start one from a built-in. Your AI assistant does the same from a description with flightdeck-new-step-type. *Where:* Step types.
+- **Light, dark, or match this computer** (Appearance). A button in the top bar steps through Match this computer, Light and Dark, and Settings has the same choice. Each browser remembers its own. *Where:* The top bar, and Settings → Appearance.
+- **One place for the team folder and setup** (Settings). Settings has the team folder (open, change, start new, examples), the people list, Jira workflows, keyboard shortcuts, and the version. *Where:* Settings.
+
+### Improved
+
+- **Six clear sections** (Navigation). The top bar has Home, Runs, Processes, Skills, Step types and Settings, and always shows where you are. Home lists only what needs you, each with one button; nothing opens on its own. *Where:* The top bar.
+- **A clear Skills page, and a page for each skill** (Skills). Skills shows the skills that need an update, the signed-off processes with no skill yet (each with Copy brief), and every skill by group and tag. Open a skill to see what changed under it and copy its update brief. The process page is shorter too: run times and who has held each role moved to How runs go. *Where:* Skills, and Processes → a process.
+- **Always know which run you're in** (Runs). On a run, a slim bar under the top bar keeps its name, process and version, where it is and how far it's got in view as you scroll, and the browser tab is named after the run, so several open runs are easy to tell apart. *Where:* Any run.
+- **Checklists, not maps** (Processes). What a process's written-down steps are called is now a checklist everywhere: the process page, the editor, the docs and the skills for your AI assistant. Team folders and files are unchanged. *Where:* Everywhere.
+- **Skills for any AI assistant, installed anywhere** (Skills). The bundled skills are plain SKILL.md files that any assistant that supports skills can use. They now go in .flightdeck/skills/ in the team folder, and flightdeck skills --to <folder> installs them anywhere else, such as your assistant's own skills folder or another repo. The old -map skill names are gone; use the -checklist ones. *Where:* flightdeck skills, and Settings → Start a new team folder.
+- **A skill's source, wherever it lives** (Skills). A skill's page shows where its source is (a repo, a shared folder or a local path) as Source, and briefs ask for that path or link when you register a skill. The location field in skills/<name>.json is unchanged. *Where:* Skills → a skill.
+
+### Fixed
+
+- **The right words after copying a brief** (Skills). Copying a skill brief says to paste it to your LLM, and gate approvals in the checklist preview show as formatted text.
+
+## 1.9.1 · Oct 18, 2026
+
+A README worth reading.
+
+### Improved
+
+- **A full guide on the package page** (Docs). The README now walks through the loop from map to skill, a sixty-second tour of the examples, every feature, the map syntax with an example that publishes as written, process-to-skill traceability end to end, the command line, the team folder, the skills for your AI assistant, how Flightdeck stays safe, upgrading from Preflight, and an FAQ. *Where:* The package page on npm.
+
+## 1.9.0 · Oct 18, 2026
+
+Process-to-skill traceability, values that flow through a run, and a hierarchy for everything.
+
+### New
+
+- **Install with npm** (Install). npm install -g @troylar/flightdeck, then flightdeck open to try it, flightdeck install <team folder> to put the app there, and flightdeck skills <team folder> to add the skills for your AI assistant. No dependencies, nothing runs on install, no network. *Where:* A terminal.
+- **See which skills implement each process** (Skills). Each process page lists the skills built from it: where each lives (any repo or folder), its own version, the process version it follows, and the steps it covers or the whole process. The map marks covered steps. *Where:* Skills, on a process page; Home → Skills.
+- **Know when a process change affects a skill** (Skills). When a new version changes the steps a skill covers, the skill shows as needing an update, with the exact before and after; if its steps didn't change, it only needs its version noted. Copy the update brief for your LLM. *Where:* Copy update brief, on a skill.
+- **Prove a version, then turn it into a skill** (Skills). Each version shows its run evidence: completed runs, clean ones, and what people did differently. With 3 clean runs the owner signs it off, and Flightdeck writes the brief an LLM needs to build the skill. The flightdeck-skill-brief skill does the same from the folder, with your AI assistant. *Where:* Ready for a skill?, on a process page.
+- **Organize processes and skills in a hierarchy, with tags** (Library). Maps and skills say group: (like Engineering / Releases) and tags:. Home shows processes and skills as foldable trees, filtered by tag. *Where:* Home → Processes and Skills.
+- **Let a step set a run detail** (Checklists). A step can say sets: tag. Checking it asks for the tag and saves it as a run detail, so every later ^tag (commands, messages, Jira fields) uses it. The start form leaves it out and says which step fills it in. Correcting it later sends the steps that used the old value back for a re-check. *Where:* sets: in a map; the example release's merge step sets the release tag.
+
+### Improved
+
+- **Preflight is now Flightdeck** (Name). It's Flightdeck: flightdeck.html, with AI assistant skills named flightdeck-*. Team folders, runs and versions carry over. A browser keeps examples and your name per file, so flightdeck.html starts those fresh; flightdeck install also updates an existing preflight.html, so people who open it keep everything. *Where:* Everywhere.
+
+## 1.8.0 · Oct 17, 2026
+
+Pause, parallel tracks, times, child runs, Jira fields and run history.
+
+### New
+
+- **Pause and resume a run** (Runs). The recorder can pause a run and say what it's waiting for. While it's paused, steps and gates can't change and timers stop; Resume picks up where it left off, and paused time never counts in durations. *Where:* Pause, in the recorder bar of a run.
+- **Work in parallel tracks** (Checklists). A phase can split into tracks, each with its own role, shown side by side. Every track finishes before the phase's gate. *Where:* ### Track: Name @role {#id} in a map.
+- **Scheduled times and a day timeline** (Runs). Steps and gates can have a clock time (at: or due:) or a due time after the run starts (after:). Each shows a badge, the Day timeline lists them in order, and the recorder's window says when one is coming up or late. *Where:* Day timeline, under the run's headline.
+- **Run another process from a step** (Runs). A {run.process} step starts a linked run of another process, passing on the details it names. The parent step is checked when that run completes, or blocked if it stops, and the child links back to its parent. *Where:* Start the run, on the step.
+- **Check transitions against your real Jira workflow** (Jira). jira/workflows.json in the team folder lists each issue type's statuses, transitions and the fields each transition requires. Maps can't publish a transition the workflow doesn't have, and a transition step asks for its required fields, with a hint for each and the value filled in from the run where the file says where it comes from. *Where:* A Jira transition step; the process page shows the workflows.
+- **Add the team's own step types** (Step types). Each step-types/<id>.json in the team folder is a step type with its own fields and evidence, checked as strictly as a map and frozen into each publication. *Where:* Team setup, on any process page.
+- **See how runs go and who has done each role** (Processes). Each process page shows outcomes, the typical time per phase, the steps that most often get blocked or done differently, and a grid of who has held each role and when. *Where:* How runs go, on a process page.
+
+### Improved
+
+- **Phase headers stay in view** (Runs). While you scroll through a phase, its header stays pinned under the top bar with the phase's progress, so you always know where you are. *Where:* Any run.
+- **Redraw only what changed** (Performance). Only the parts of the screen that changed are redrawn, so focus, the caret and anything you're typing stay exactly where they were.
+- **Examples that show everything** (Getting started). The examples now come with a month of team history: earlier releases (one stopped early) behind the analytics and role grid, a release whose check-in ran as a linked child run with its Jira fields filled in, an incident in progress split into tracks, and a sprint start that's paused, with its meeting time coming up. *Where:* Home → Try the examples (Reset examples to see them in a browser that already has the old ones).
+
+### Fixed
+
+- **Fewer leftover save receipts and copies** (Saving). A save receipt that matches the current run is cleaned up instead of being shown as a conflict copy, and removing a copy also removes identical receipts.
+
+## 1.7.0 · Oct 17, 2026
+
+See what's new, and know when a newer copy is waiting.
+
+### New
+
+- **Read what changed in each version** (Updates). What's new in the top bar shows the version you're on and the full release history: search it, filter by new, improved or fixed and by area, and see before and after for each change. A dot appears when there's a release you haven't seen, and a short notice appears once after an update. *Where:* What's new, in the top bar.
+- **Know when a newer Flightdeck is in the team folder** (Updates). If someone saves a newer flightdeck.html at the top of the team folder, older copies say so in the top bar, so everyone can switch to it. *Where:* The top bar, after opening or refreshing the team folder.
+
+## 1.6.0 · Oct 17, 2026
+
+Every save survives, on one computer or many.
+
+### Improved
+
+- **Keep both versions when two windows save at once** (Saving). Windows on one computer save a run one at a time. Across browsers and computers, each save first leaves its own receipt; a save that another one replaced shows up in the run as a conflict copy to compare and keep. *Where:* The panel at the top of a run, when it has other versions.
+- **Give each window its own files** (Saving). Notes, history, plan decisions and screenshots are written by each window to its own files, so a duplicated tab or a second window can never overwrite them.
+
+### Fixed
+
+- **Keep the newest change through slow refreshes and failed saves** (Saving). A refresh never brings back an older version of a run over a change you just made, a save still in progress, or one that failed. Try again always saves your newest change.
+- **Keep what you're still typing** (Notes). Finishing one note clears only that note. Text typed while it saved, other steps' drafts and their screenshots stay. Notes over 2,000 characters are refused with a message instead of being cut short.
+
+## 1.5.0 · Oct 17, 2026
+
+AI assistant skills for writing and improving maps.
+
+### New
+
+- **Write, review and improve maps with your AI assistant** (AI assistant). Every team folder carries six skills for your AI assistant: write a new map, edit one, review one, learn from recent runs, plan a run and summarize the folder. A checker in the skills judges published versions and plan decisions exactly as Flightdeck does. *Where:* Open the team folder with your AI assistant and ask for a skill by name, such as flightdeck-status.
+
+### Improved
+
+- **Start a new team folder with everything in it** (Getting started). Start a new team folder adds you to people.json, a starter map, the guide for AI assistants and the Flightdeck skills. It refuses a folder that isn't empty. *Where:* Home → Get started.
+
+## 1.4.0 · Oct 17, 2026
+
+Finish runs well, recover safely, and work faster.
+
+### New
+
+- **Finish a run with follow-ups and map changes** (Runs). End run opens a short finish: add follow-ups with an owner and Jira ticket, review suggested map changes from "did it differently" answers and map-change notes, then choose the outcome. The receipt includes all of it, and follow-ups from the last 30 days show on Home. *Where:* End run in any run you're recording.
+- **Compare and keep conflict copies in the app** (Recovery). A run with other versions shows a panel to compare each one, keep it (the current version is saved beside it first) or delete it. Nothing is merged without you choosing. *Where:* The panel at the top of a run.
+- **Choose how to begin** (Getting started). Home offers three paths: try the examples, open your team folder (with the OneDrive tip to keep it on this device), or start a new team folder.
+
+### Improved
+
+- **Run a checklist on your own** (Solo runs). Starting a run asks On my own or With others. Solo runs hide roles and screen sharing, and confirming a phase is one click.
+- **Refresh only what's open** (Performance). While a run is open, Flightdeck rereads just that run every few seconds. Published versions and finished runs are remembered, so large team folders stay quick.
+- **Easier with a keyboard and screen reader** (Accessibility). Single-key shortcuts can be turned off, dialogs return focus when closed, errors appear next to their field, form fields have stronger borders, and messages are announced. *Where:* Press ? for keyboard help and the shortcut switch.
+
+## 1.3.0 · Oct 17, 2026
+
+Fill in values as they become known.
+
+### New
+
+- **Fill in or correct a step's values mid-run** (Runs). Some values aren't known until the middle of a release. The recorder can fill in a step's details and evidence before or after checking it; each change is logged with its old value, and the map's own value stays visible. *Where:* Fill in, on any step.
+
+### Improved
+
+- **Describe a step with only what's known** (Checklists). A step can name only what's known; a missing usual field is a tip, not an error. Evidence is required only where the map says require: or evidence:.
+
+## 1.2.0 · Oct 17, 2026
+
+Clearer headings and runs for one.
+
+### New
+
+- **Runs for one person** (Solo runs). A run with nobody but you assigned drops the team wording, and a map can say runs: solo to skip assigning roles.
+
+### Improved
+
+- **The same headings on every computer** (Look). Headings use a built-in typeface, so Windows and Mac show the same thing, and code-style text is used only for commands, values and times.
+
+## 1.1.0 · Oct 17, 2026
+
+Step types that fit the work.
+
+### New
+
+- **Jenkins, pull request and Jira steps** (Step types). New step types for a Jenkins job, a Bitbucket pull request and a Jira issue, each with the fields that matter to it.
+- **Record evidence when you check a step** (Evidence). Steps can record a build number, a pull request link, a decision or a review verdict. It shows on the step and on the receipt.
+
+## 1.0.0 · Oct 17, 2026
+
+Flightdeck.
+
+### New
+
+- **Versioned process maps** (Checklists). Write a process as a checklist map with phases and gates, publish it as a numbered version, and see every version with its change note and differences.
+- **Run a checklist together** (Runs). One person records while others follow along and add notes and screenshots. Gates approve exactly what they say, and changing a detail like the commit sends tied steps back for a re-check.
+- **Timers, deadlines and a receipt** (Runs). Start a step to time it, copy a deadline from the real tool to see a countdown, and copy a receipt into Jira when you're done.

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Troy Larson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The Barlow Condensed fonts embedded in dist/flightdeck.html are licensed separately under the
+SIL Open Font License 1.1; see dist/FONT-LICENSE.txt.

package/README.md

@@ -0,0 +1,384 @@
+<div align="center">
+
+<picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/banner-dark.png"><img src="https://raw.githubusercontent.com/troylar/flightdeck/main/docs/images/banner-light.png" alt="Flightdeck: fly it by hand, then put it on autopilot" width="1000"></picture>
+
+<br>
+
+[![npm](https://img.shields.io/npm/v/@troylar/flightdeck?color=e7a300&label=npm)](https://www.npmjs.com/package/@troylar/flightdeck)
+[![license](https://img.shields.io/badge/license-MIT-1d7650)](#license)
+[![dependencies](https://img.shields.io/badge/dependencies-0-1d7650)](#safe-by-design)
+[![offline](https://img.shields.io/badge/runs-offline-16202a)](#safe-by-design)
+[![node](https://img.shields.io/badge/node-%E2%89%A518-5a55a8)](#install)
+
+**[Install](#install)** · **[Tour](#a-tour)** · **[Write a checklist](#a-checklist-in-twenty-lines)** · **[Process to skill](#process-to-skill-traceability)** · **[FAQ](#faq)**
+
+</div>
+
+<br>
+
+Every team has processes that live in someone's head: the release, the check-in, the incident, the sprint start. Flightdeck writes them down as **checklists**, runs them with **gates** between phases, and keeps a record of every run. Once a version is proven, it becomes the brief your AI assistant uses to build a **skill**: reusable instructions for the assistant. Flightdeck links each registered skill to the process version and steps it follows, and flags when a process change affects it.
+
+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>
+
+<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>
+
+Flightdeck keeps checklists and run records together, links to skills stored elsewhere, and flags process changes that affect them.
+
+<br>
+
+## Install
+
+```bash
+npm install -g @troylar/flightdeck
+
+flightdeck open                        # opens the app on built-in examples
+flightdeck install ~/OneDrive/Team     # puts flightdeck.html in your team folder
+flightdeck skills  ~/OneDrive/Team     # adds the skills for your AI assistant there
+```
+
+Then open `flightdeck.html` from the team folder, go to **Settings → Open team folder**, pick the same folder, and choose who you are in the top right. That's the whole setup.
+
+> **Prefer no npm?** `flightdeck.html` is self-contained. Copy it anywhere and open it.
+
+<br>
+
+## A tour
+
+`flightdeck open` starts on a team folder with a month of history in it. Choose **Casey Nguyen** in the top right and follow along. Six sections sit in the top bar: **Home, Runs, Processes, Skills, Step types, Settings**.
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+**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>
+
+</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>
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+**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>
+
+</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.
+
+<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>
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+**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>
+
+</td>
+<td valign="top">
+
+**A skill** says what changed under it and gives your LLM the exact before and after.
+
+<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>
+
+</td>
+</tr>
+</table>
+
+<br>
+
+## What it does
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+### Checklists with teeth
+Every phase ends at a **gate**. Nothing after it opens until someone passes it, and a gate approves exactly what it says: `deploy of d9d8514 to production`. Must-do steps can't be skipped. Change the commit mid-run and every step tied to it comes back for a re-check.
+
+</td>
+<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.
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+### Steps that know their tools
+Steps are typed: `jenkins.job`, `bitbucket.pr`, `jira.issue`, `run.command`, `decide`, `review` and more, plus your team's own types. Each asks for the evidence that matters (a build number, a PR link, a decision) only where the checklist says it's required.
+
+</td>
+<td valign="top">
+
+### Jira, the way it really is
+Point Flightdeck at your real Jira workflow and a transition can't publish if Jira can't make it. Checking it asks for the transition's required fields, with a hint for each, and fills in the ones it can from the run.
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+### Time, tracks and pauses
+Give a step a clock time, a deadline, or "within 2 hours of starting" and it gets a badge, a place on the day timeline, and a reminder. Split a phase into parallel tracks. Pause a run with a reason; paused time never counts.
+
+</td>
+<td valign="top">
+
+### Processes inside processes
+A step can start another process as a linked child run, passing on the details it needs. The parent step is checked only when that child completes, with the same values it was started for.
+
+</td>
+</tr>
+<tr>
+<td valign="top">
+
+### Values that flow
+A step can **set** a run detail: the merge step records the release tag, and every later `^tag` in commands, messages and Jira fields uses it. Correct it later and the steps that used the old value come back for a re-check.
+
+</td>
+<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.
+
+</td>
+</tr>
+</table>
+
+<br>
+
+## A checklist, in twenty lines
+
+Checklists are Markdown. Your LLM writes them; people publish them.
+
+```markdown
+---
+process: release
+title: Production release
+group: Engineering / Releases
+tags: production, deploy
+owner: person-casey
+context: ticket, commit, environment, tag
+roles: release-lead, qa, backend
+---
+
+## Before production changes · DO-CONFIRM {#prep}
+- [!] {ci.gate} Full test gate green on the release commit ^commit {#tests}
+  require: run
+
+## Gate: Ready to deploy · owner @release-lead {#ready}
+  approves: deploy of `^commit` to ^environment
+
+## Deploy · READ-DO {#deploy}
+- [!] {bitbucket.pr} Merge the release branch to master ^commit @release-lead {#merge}
+  sets: tag
+- [!] {jenkins.job} Start the production deploy job ^tag @backend {#jenkins}
+  parameters: TICKET=^ticket TAG=^tag
+  after: 2h
+```
+
+| Mark | Means |
+|---|---|
+| `[!]` · `[ ]` · `[~]` | Must do · a step · automation planned |
+| `{type}` | What kind of step, so it knows its fields and evidence |
+| `@role` · `^detail` | Who does it · a run detail it depends on (change the detail, redo the step) |
+| `sets: tag` | This step produces a run detail later steps use |
+| `## Gate:` · `approves:` | The pause point, and exactly what passing it approves |
+| `### Track: Name @role` | Parallel work inside a phase |
+| `at:` · `due:` · `after:` | A clock time, a deadline, or a due time after the run starts |
+| `{run.process}` · `carry:` | Start another process as a linked child run, passing these details |
+| `group:` · `tags:` | Where the process sits in your hierarchy, and how to find it |
+
+Publishing freezes a checklist as a numbered version, with who, when and why. Runs keep the version they started with, forever. The full format is in [docs/map-format.md](https://github.com/troylar/flightdeck/blob/main/docs/map-format.md).
+
+<br>
+
+## Manage your templates in the app
+
+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.
+- **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**.
+- **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.
+
+**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.
+
+<br>
+
+## 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:
+
+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.
+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>
+
+<br>
+
+## Process-to-skill traceability
+
+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.
+
+**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.
+
+**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:
+
+```json
+{
+  "name": "release-deploy",
+  "version": "1.3.0",
+  "location": "https://bitbucket.example.com/projects/WA/repos/team-skills/browse/release-deploy",
+  "implements": "release@4",
+  "steps": ["merge", "jenkins"],
+  "group": "Engineering / Releases",
+  "tags": ["deploy"]
+}
+```
+
+Leave out `steps` for a skill that covers the whole process. A process can have many skills.
+
+**5. Stay in step.** When a new version is published, every skill is checked against it:
+
+| Status | Meaning | What you do |
+|---|---|---|
+| **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 |
+| **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.
+
+<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>
+
+<br>
+
+## Command line
+
+| Command | Does |
+|---|---|
+| `flightdeck open` | Opens the app on its built-in examples |
+| `flightdeck install <folder>` | Copies `flightdeck.html` into a team folder. Won't replace a newer copy or an unrecognized file without `--force`. Also updates a `preflight.html` already there |
+| `flightdeck skills <folder>` | Adds or updates the skills for your AI assistant in `<folder>/.flightdeck/skills`. Leaves files someone changed alone unless you add `--force` |
+| `flightdeck skills --to <dir>` | The same, into any other folder you name (absolute or relative), such as your assistant's own skills folder or another repo. `<dir>` is created if it's missing |
+| `flightdeck path` | Prints where the app file is |
+| `flightdeck version` | Prints the version |
+
+<br>
+
+## The team folder
+
+```
+people.json            who's on the team
+maps/drafts/           checklists being written (Markdown)
+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
+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
+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.
+
+<br>
+
+## Skills for your AI assistant
+
+`flightdeck skills` installs these into the team folder's `.flightdeck/skills/`, or anywhere else with `--to <dir>`. They're plain `SKILL.md` files (a name, a description and instructions), so any assistant that supports skills can use them: install them where your assistant looks for skills, or point it at the folder. Then open the team folder with your assistant and ask for one by name:
+
+| Skill | Does |
+|---|---|
+| `/flightdeck-new-checklist` | Turns a runbook, notes or a conversation into a checklist |
+| `/flightdeck-edit-checklist` | Changes a checklist and keeps its step IDs |
+| `/flightdeck-review-checklist` | Checks a checklist for format errors and quality, without changing it |
+| `/flightdeck-learn-from-runs` | Turns what actually happened in runs into suggested checklist changes |
+| `/flightdeck-plan-run` | Plans the next run, rotating roles fairly |
+| `/flightdeck-status` | Summarizes the folder: what needs a person, what's running, what's stale |
+| `/flightdeck-new-step-type` | Creates or changes a team step type from a description |
+| `/flightdeck-skill-brief` | Writes the brief to create a skill from a signed-off version, or update one |
+
+<br>
+
+## Safe by design
+
+- **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.
+- **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.
+
+<br>
+
+## Coming from Preflight
+
+Flightdeck was called Preflight before 1.9.0. Team folders, runs and published versions carry over untouched. `flightdeck install` also updates a `preflight.html` already in the folder, so anyone still opening that file gets the new version and keeps what their browser saved. A browser keeps saved examples and your name per file, so `flightdeck.html` starts those fresh.
+
+<br>
+
+## 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.
+
+**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.
+
+**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.
+
+**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.
+
+**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.
+
+**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).
+
+**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).
+
+<br>
+
+## License
+
+[MIT](https://unpkg.com/@troylar/flightdeck/LICENSE). The embedded Barlow Condensed fonts are licensed under the SIL Open Font License 1.1; see [`dist/FONT-LICENSE.txt`](https://unpkg.com/@troylar/flightdeck/dist/FONT-LICENSE.txt).
+
+<div align="center">
+<br>
+
+*Inspired by* The Checklist Manifesto: *a checklist doesn't fly the plane. It makes sure the crew doesn't forget the things that matter.*
+
+</div>