@troylar/flightdeck 2.12.0 → 2.12.2

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 <!-- Generated by build.py from src/releases.json. Edit that file, not this one. -->
 
+## 2.12.2 · Nov 2, 2026
+
+AGENTS.md says what an assistant's draft checks really cover.
+
+### Fixed
+
+- **AGENTS.md says what draft checks load** (AI assistants). They say what the checks load and what they don't: people, step types, Jira workflows and which checklists are published. AGENTS.md lists flightdeck export. Update with flightdeck install or Settings; Team notes stay as they are. *Where:* Settings › AI assistant files
+
+## 2.12.1 · Nov 2, 2026
+
+Get your AI assistant started, and let it read all its instructions.
+
+### New
+
+- **Copy instructions for your assistant** (Settings). One button copies a first prompt for your assistant. It says to read AGENTS.md to the end, says where the skills are, and asks what you want done. Open the team folder itself as the workspace, in Agent mode, then paste it. *Where:* Settings › AI assistant files
+- **Download skills ZIP** (Settings). Download the skills as a ZIP, made from what's already in the app file, with no network and no folder needed. It holds the same files flightdeck skills --to writes. What each skill is for, and what to ask for: docs/skills.md. *Where:* Settings › AI assistant files
+
+### Fixed
+
+- **AGENTS.md is short enough to be read to the end** (AI assistants). AGENTS.md is under 28 KiB, the safety rules come first, and the long formats moved to .flightdeck/skills/_flightdeck/file-formats.md. Every rule stays. Update it with flightdeck install or Settings; Team notes stay as they are. Keep Team notes to about 4 KiB.
+- **A folder set up by a newer version is left alone** (AI assistants). flightdeck install, Settings and Folder health leave a folder a newer version set up alone, in the same words. An old default an older app left waiting is named, with its path, never merged or counted; it's safe to delete by hand. *Where:* Settings › AI assistant files
+
 ## 2.12.0 · Nov 1, 2026
 
 AI assistant files, from the app.

package/README.md

@@ -25,7 +25,7 @@
 ## Quick start
 
 1. `npx @troylar/flightdeck open` opens the app in your browser (needs Node 18 or later).
-2. No Node? Save [flightdeck.html](https://unpkg.com/@troylar/flightdeck@2.12.0/dist/flightdeck.html) from the npm package as a file (right-click, **Save link as…**) and open that file in Edge or Chrome.
+2. No Node? Save [flightdeck.html](https://unpkg.com/@troylar/flightdeck@2.12.2/dist/flightdeck.html) from the npm package as a file (right-click, **Save link as…**) and open that file in Edge or Chrome.
 3. Choose **Look around the examples** to try it, or **Start your team** to set up your team's folder.
 
 <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 on the run screen: 7/15 answered in the header with Details, Screen share, Receipt and More; a strip saying you're recording, with Pause and Hand off and the run's details; Phases with each gate's state; the checklist with Next up pinned at its top; and the selected step, whose text shows the run's tag (Start the production deploy job v2026.10.16), with the values to copy, Record the result, Done, Done differently and Blocked" width="1000"></picture></a></p>
@@ -373,7 +373,7 @@ Thousands of runs open and refresh without stalling. Long lists show a page at a
 
 ## Skills for your AI assistant
 
-**Settings → AI assistant files** in the app (or `flightdeck install` in a terminal) puts these in the team folder's `.flightdeck/skills/`, with an `AGENTS.md` that any assistant reads. They're plain `SKILL.md` files, so any assistant that supports skills can use them. Open the team folder with your assistant and ask for one by name:
+**Settings → AI assistant files** in the app (or `flightdeck install` in a terminal) puts these in the team folder's `.flightdeck/skills/`, with an `AGENTS.md` that any assistant reads. They're plain `SKILL.md` files, so any assistant that supports skills can use them. Open the team folder itself as the workspace (in Agent mode, for Copilot in VS Code) and start with **Copy instructions for your assistant** on that screen. Then say what you need, or ask for a skill by name. [Skills for your AI assistant](https://github.com/troylar/flightdeck/blob/main/docs/skills.md) lists each one by job, with what to ask for:
 
 | Skill | Does |
 |---|---|
@@ -390,7 +390,7 @@ In `AGENTS.md`, only the part between the `flightdeck:begin` and `flightdeck:end
 
 ### AI assistant files, from the app
 
-**Settings → AI assistant files** installs and updates `AGENTS.md` and the skills without a command line. Each file shows where it stands:
+**Settings → AI assistant files** installs and updates `AGENTS.md` and the skills without a command line. **Copy instructions for your assistant** copies the first prompt to paste, and **Download skills ZIP** gives you the skills as a file, with no folder and no network. Each file shows where it stands:
 
 | Status | Means |
 |---|---|
@@ -477,6 +477,7 @@ Flightdeck was called Preflight before 1.9.0. Team folders, runs and published v
 |---|---|---|
 | [Checklist format](https://github.com/troylar/flightdeck/blob/main/docs/map-format.md) | Anyone writing checklists, and their AI assistant | Every mark, field and step type, and what stops a checklist from publishing |
 | [Flightdeck and OneDrive](https://github.com/troylar/flightdeck/blob/main/docs/onedrive.md) | Whoever sets up the team folder | What keeps runs safe on a synced folder, and what it can't promise |
+| [Skills for your AI assistant](https://github.com/troylar/flightdeck/blob/main/docs/skills.md) | Anyone working with an AI assistant | Starting one, what to ask for, each skill by job |
 | [Updating Flightdeck](https://github.com/troylar/flightdeck/blob/main/docs/updating.md) | Whoever keeps the team's copy current | A step-by-step update, mixed versions and rolling back |
 | [When something goes wrong](https://github.com/troylar/flightdeck/blob/main/docs/recovery.md) | Anyone who sees a warning | What each problem means and what to do, step by step |
 | [Evidence packs](https://github.com/troylar/flightdeck/blob/main/docs/evidence.md) | Anyone who needs proof of a run | What's in a pack and how to check it |

package/bin/flightdeck.js

@@ -190,6 +190,14 @@ function classify(t, files, base, force) {
     const parts = f.rel.split('/'), now = readInside(t.dir, parts), want = hash(managed(f.key, f.text));
     return { key: f.key, rel: f.rel, baseKey: f.baseKey, parts, text: f.text, now, want, have: now === null ? null : hash(managed(f.key, now)), staged: staged(t, f.rel) };
   });
+  /* An old copy an older app left (PF.contract.classifyCopies, the app's own rule, from the texts as read: a byte-order mark
+     kept): named, never merged, counted or removed. */
+  const K = contractRules();
+  items.forEach((i) => {
+    const all = i.staged, said = JSON.parse(JSON.stringify(K.classifyCopies({ key: i.key, baseKey: i.baseKey, shipped: i.text, version: t.version, base, active: i.now, copies: all.map((x) => ({ version: x.version, text: x.text })) })));
+    i.old = all.filter((x, n) => said[n] === 'old');
+    i.staged = all.filter((x, n) => said[n] !== 'old');
+  });
   const why = decide(items.map((i) => ({ key: i.key, baseKey: i.baseKey, want: i.want, have: i.have, staged: i.staged.map((x) => ({ version: x.version, hash: hash(managed(i.key, x.text)) })) })), t.record, base, t.version, force);
   return items.map((i, n) => Object.assign(i, why[n], { key: i.key }));
 }
@@ -234,37 +242,23 @@ function merged(item) {
 }
 /* A record written by a newer Flightdeck (flightdeck-installed/2 on, or a must-understand feature): never read for meaning and
    never rewritten. The same verdict as PF.contract.cleanInstalled (test/cli.test.js checks they agree). */
-function installedNewer(r) {
-  if (!r || typeof r !== 'object' || Array.isArray(r)) return '';
-  const m = typeof r.format === 'string' ? /^([a-z][a-z0-9-]{1,59})\/([1-9]\d{0,3})$/.exec(r.format) : null;
-  if ((m && m[1] === 'flightdeck-installed' && m[2] !== '1') || (m && m[1] === 'flightdeck-installed' && (Array.isArray(r.features) ? r.features.length > 0 : r.features != null))) return 'was written by a newer Flightdeck' + (typeof r.version === 'string' && /^\d+\.\d+\.\d+$/.test(r.version) ? ' (' + r.version + ')' : '') + '.';
-  return '';
-}
+function installedNewer(r, mine) { return contractRules().recordNewer(r, mine); }
+/* The app's own contract rules (PF.contract), from this package's app file, so a verdict the app, Folder health and this
+   command all reach is one function, never a copy. */
+let engineRules = null;
+function contractRules() { return (engineRules = engineRules || loadEngine().PF.contract); }
 /* The folder's record, checked field by field. Anyone can edit it, so a record that isn't exactly what this command writes is
    ignored (and said so), and only entries for files this version installs, with a well-formed hash, are read. */
 function readRecord(t, keys) {
   t.recordText = readInside(t.dir, t.recordAt);
-  const r = parseRecord(t.recordText, keys);
-  if (r.newer) fail(path.join(t.dir, ...t.recordAt) + ' ' + r.newer + ' Nothing was changed. Use the newer Flightdeck package.');
+  const r = parseRecord(t.recordText, keys, t.version);
+  if (r.newer) fail(contractRules().outcomeWords({ state: 'newer', newer: r.newer }, { home: t.home, updates: t.updates, recordAt: t.recordAt.join('/'), version: t.version }).text);
   return r;
 }
 /* The record's text as install reads it: the same as PF.contract.readRecord (test/assistant-files.test.js checks they agree). */
-function parseRecord(text, keys) {
-  const none = { files: {} };
-  if (text === null || text === undefined) return none;
-  let r = null;
-  try { r = JSON.parse(text); } catch (e) { /* ignored below */ }
-  const newer = installedNewer(r);
-  if (newer) return { newer };
-  const ok = r && typeof r === 'object' && !Array.isArray(r) && r.format === 'flightdeck-installed/1' && typeof r.version === 'string' && /^(\d+\.\d+\.\d+|dev)$/.test(r.version)
-    && typeof r.at === 'string' && (r.by === 'cli' || r.by === 'app') && r.files && typeof r.files === 'object' && !Array.isArray(r.files)
-    && Object.keys(r.files).every((k) => typeof r.files[k] === 'string' && /^[0-9a-f]{64}$/.test(r.files[k]));
-  if (!ok) return Object.assign(none, { ignored: true });
-  /* files: what this command may consult; all: every entry, kept as it is for files this command doesn't handle. */
-  const files = {};
-  keys.forEach((k) => { if (Object.prototype.hasOwnProperty.call(r.files, k)) files[k] = r.files[k]; });
-  return { version: r.version, files, all: Object.assign({}, r.files) };
-}
+/* The record's text as install reads it: the app's own PF.contract.readRecord, so the app and this command parse it the same way
+   (copied out of the engine's context, so it compares as a plain object here). */
+function parseRecord(text, keys, mine) { return JSON.parse(JSON.stringify(contractRules().readRecord(text === undefined ? null : text, keys, mine))); }
 function stamp(d) { const p = (n) => String(n).padStart(2, '0'); return d.getFullYear() + '-' + p(d.getMonth() + 1) + '-' + p(d.getDate()) + ' ' + p(d.getHours()) + p(d.getMinutes()); }
 function fineStamp(d) { const p = (n, w) => String(n).padStart(w || 2, '0'); return stamp(d).replace(' ', '-') + p(d.getSeconds()) + '-' + p(d.getMilliseconds(), 3); }
 
@@ -417,6 +411,7 @@ const LABEL = { current: 'up to date', update: 'updated', new: 'added', missing:
 const CHECK_LABEL = { update: 'update available', new: 'will be added', missing: 'will be added again', merge: 'needs merge', forced: 'will be replaced (--force)', kept: 'kept (your team changed it)' };
 function report(items, check, out) {
   items.filter((i) => i.status !== 'current').forEach((i) => out.push('  ' + (i.changed ? 'changed during install' : (check ? CHECK_LABEL : LABEL)[i.status]).padEnd(28) + i.rel + (i.waiting ? ' (still waiting in updates/' + i.waiting + ')' : '')));
+  items.filter((i) => i.old && i.old.length).forEach((i) => out.push('  ' + 'old copy, nothing to merge'.padEnd(28) + i.rel + ' (left in updates/' + i.old.map((x) => x.version).join(', ') + ' by an older Flightdeck; safe to delete by hand)'));
 }
 /* What install says after the file list: an ignored record, and files left alone because they changed while it ran. */
 function notes(t, out) {