@bongos/core 1.20.2 → 1.20.3

package/modules/hall-ui/public/settings.css

@@ -202,7 +202,9 @@ select.voices__select { min-width: 140px; }
 /* The adopted contract, shown in full before "Use this" — another builder's prose
    reaching your sessions is the one thing here that must never be folded away. */
 .speciality-contract { flex-basis: 100%; margin-top: 0.5rem; font-size: 0.85rem; }
-.speciality-contract > summary { cursor: pointer; opacity: 0.85; }
+/* 24px tall: the panel was never revealed until task 1004073, so the kit had
+   never measured this toggle; it came back 21px. */
+.speciality-contract > summary { cursor: pointer; opacity: 0.85; min-height: 24px; padding-block: 2px; box-sizing: border-box; }
 .speciality-contract__body {
   white-space: pre-wrap;
   margin: 0.4rem 0 0;
@@ -212,6 +214,55 @@ select.voices__select { min-width: 140px; }
   font-family: inherit;
   opacity: 0.92;
 }
+/* The skills walkthrough (task 1004073, ADR 0310 §3): one offered skill at a
+   time, three answers as a definition list, then a decision. It sits inside the
+   card like the train form, so it inherits the card's ground in both modes. */
+.skill-walk {
+  flex-basis: 100%;
+  margin-top: 0.75rem;
+  padding-top: 0.75rem;
+  border-top: 1px solid var(--rule);
+  display: flex;
+  flex-direction: column;
+  gap: 0.6rem;
+}
+/* The measure caps the reading lines, never the section: a capped flex-basis
+   lets the section fit beside the card's actions instead of wrapping under them. */
+.skill-walk > * { max-width: var(--measure); }
+.skill-walk__progress { margin: 0; font-size: 0.8rem; color: var(--ink-soft); }
+.skill-walk__name { margin: 0; font-family: var(--font-mono); font-size: 1rem; color: var(--ink); }
+.skill-walk__facts { margin: 0; display: grid; gap: 0.2rem 0; }
+.skill-walk__facts dt { font-size: 0.8rem; color: var(--ink-soft); margin-top: 0.4rem; }
+.skill-walk__facts dt:first-child { margin-top: 0; }
+.skill-walk__facts dd { margin: 0; color: var(--ink); line-height: 1.5; }
+.skill-walk__note { font-size: 0.8rem; }
+/* "Leave it off" and "Turn it on" are the panel family's plain pill at EQUAL
+   weight: the default is off, so the page must not lean on the reader toward on.
+   Only "Save my choices" takes the accent. A decision already made reads through
+   aria-pressed when the person steps Back to it. */
+.skill-walk__actions { flex-wrap: wrap; }
+.skill-walk__actions .pbtn[aria-pressed="true"] { border-color: var(--ink-soft); }
+.skill-walk__recap { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 0.5rem; }
+.skill-walk__recap li { display: flex; flex-wrap: wrap; align-items: baseline; gap: 0 0.4rem; }
+.skill-walk__recap .prow__hint { flex-basis: 100%; margin: 0; }
+.skill-walk__recap strong { font-family: var(--font-mono); font-weight: 600; }
+/* "Finish later" is a way out, not a choice about a skill, so it reads as a quiet
+   link below the decision rather than a third button beside it. */
+.skill-walk__later {
+  align-self: flex-start;
+  background: none;
+  border: 0;
+  padding: 0 0.25rem;
+  margin-inline-start: -0.25rem;
+  min-height: 24px;
+  font: inherit;
+  font-size: 0.8rem;
+  color: var(--ink-soft);
+  text-decoration: underline;
+  text-underline-offset: 3px;
+  cursor: pointer;
+}
+.skill-walk__later:hover { color: var(--ink); }
 
 /* ---- Software update (task 1004296) -------------------------------------- */
 /* A version is read digit by digit and compared against another, so it takes the mono

package/modules/hall-ui/public/settings.states.json

@@ -9,7 +9,8 @@
   "states": {
     "account": { "auth": true, "actions": [["wait", 900]], "expect": { "visible": ["#settings-h1", "#display-name-input", "#craft-chips"] } },
     "access": { "auth": true, "url": "/settings#access", "actions": [["wait", 900]], "expect": { "visible": ["#cli-reissue-btn", "#sessions-list", "#artkey-card"] } },
-    "preferences": { "auth": true, "url": "/settings#preferences", "actions": [["wait", 900]], "expect": { "visible": ["#wander-rows", "#render-rows"] } },
+    "preferences": { "auth": true, "url": "/settings#preferences", "actions": [["wait", 900]], "expect": { "visible": ["#wander-rows", "#render-rows", "#specialities-rows"] } },
+    "skills-walkthrough": { "auth": true, "url": "/settings#preferences", "actions": [["wait", 900], ["click", "#specialities-rows button[data-act=\"adopt\"]"], ["wait", 700]], "expect": { "visible": [".skill-walk", ".skill-walk__facts", "button[data-walk=\"on\"]", "button[data-walk=\"off\"]"] } },
     "sound": { "auth": true, "url": "/settings#sound", "actions": [["wait", 900]], "expect": { "visible": ["#voices-table", "#sound-rows", "#event-sound-rows"] } },
     "update": { "auth": true, "url": "/settings#software-update", "actions": [["wait", 1200]], "expect": { "visible": ["#software-update-h", "#su-body", "#su-update", ".su-versions"] } }
   },

package/modules/hall-ui/records/panel-family.md

@@ -26,3 +26,5 @@ Also fixed here, as the board task handed forward: the two sub-24px links on Hom
 - **"Up to date" is said only from an answer.** A failed registry read, an unnamed running version and unread release notes each render as what they are; unread notes are never drawn as a version with no changes.
 - **The notes are the soft ink, underlined, on the platform.** There every entry links to its task, and a list of accent-coloured sentences read as a warning. Elsewhere the ids belong to another project's ledger, so the entries are plain text.
 - **Kit:** `settings.states.json` `update`, ALL CLEAN at 1440/390/320 × dark/light against the harness with the fixture `software-update.json` (a live reading for 1.19.1033). Tests: `tests/software_update.mjs`.
+
+**Settings: adopting a speciality walks through its skills (task 1004073, ADR 0310 §3)** — the owner ruled an adopted speciality's skills start OFF "and you should walk through what comes with each". So adopting one that offers skills opens `.skill-walk` inside its card: one skill per step (what it does, when to reach for it, what it costs, what it needs, who can run it), "Leave it off" / "Turn it on" at EQUAL weight (plain `.pbtn`, no accent — the default is off, so the page must not lean toward on), Back, then a recap restating each skill in a line, then ONE `PUT` of the whole set. "Finish later" saves nothing. Focus moves to each new step heading. Two things found on the way: the specialities panel shipped `hidden` and nothing ever revealed it, so adoption was unreachable from the hall; and its contract `<summary>` measured 21px once visible (now 24). **Kit:** `settings.states.json` `skills-walkthrough` + `preferences`, ALL CLEAN at 1440/390/320 × dark/light against the harness, with fixtures `specialities*.json` built from the real skills on disk and canned answers for adopt and save. Tests: `tests/speciality_walkthrough_ui.mjs` (runs the real page script).

package/modules/specialities/routes/specialities.js

@@ -401,6 +401,33 @@ module.exports = function buildSpecialitiesRouter() {
     res.json({ adoption });
   }));
 
+  // GET /specialities/:id/skills — what the adoption WALKTHROUGH shows (task
+  // 1004073, ADR 0310 §3): each skill the speciality offers, explained for the
+  // person deciding (what it does, when to reach for it, what it costs, what it
+  // needs), plus the caller's own enabled set and whether they hold it at all.
+  // Same visibility as GET /specialities/:id — 404 for a row you cannot see. An
+  // offered skill this instance no longer has comes back `installed: false`, so
+  // the walkthrough can say so instead of offering something that would 404.
+  // Read-only; rank: any builder who may see the speciality.
+  router.get('/specialities/:id/skills', api.requireBuilder, asyncHandler('GET /specialities/:id/skills', async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_id' });
+    if (id === null) return;
+    const s = await db.getSpeciality(id);
+    if (!s || !(await visibleTo(s, req.builder))) return res.fail('not_found', 404);
+    const installed = installedSkills();
+    const offered = Array.isArray(s.skills) ? s.skills : [];
+    const skills = offered.map((name) => (installed.has(name)
+      ? { ...skillsLib.explainSkill({ name, ...installed.get(name) }), installed: true }
+      : { name, installed: false }));
+    const mine = (await db.listAdoptions(req.builder.id)).find((a) => String(a.id) === String(id) && a.active);
+    res.json({
+      speciality: { id: s.id, name: s.name, discipline: s.discipline },
+      adopted: !!mine,
+      enabled: mine && Array.isArray(mine.enabled_skills) ? mine.enabled_skills : [],
+      skills,
+    });
+  }));
+
   // PUT /specialities/:id/skills — the caller's ENABLED set for a speciality they
   // hold (task 1004072, ADR 0310 §2). Replaces the set whole: the walkthrough
   // (task 1004073) sends the decisions it collected, so a partial patch would

package/modules/specialities/skills.js

@@ -35,29 +35,125 @@ function listDirs(dir) {
   } catch { return []; }
 }
 
-// The description line from a SKILL.md's frontmatter, for the adoption
-// walkthrough (task 1004073) to show. Flat `description: ...` only, the grammar
-// every SKILL.md here uses; anything else reads as no description.
+// The top-level keys of a SKILL.md's frontmatter, as strings (a flow list
+// `[a, b]` as an array). Enough YAML for the grammar SKILL.md files use: a flat
+// `key: value`, a quoted value, and a folded or literal block (`>-`, `>`, `|`,
+// `|-`) whose indented lines follow. Part 1 read only the flat form, and almost
+// every skill here folds its description, so each read as `>-` (task 1004073).
+// Anything it cannot read is simply absent.
+function parseFrontmatter(text) {
+  const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(String(text || ''));
+  if (!fm) return {};
+  const lines = fm[1].split(/\r?\n/);
+  const out = {};
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^([A-Za-z][\w-]*):\s*(.*)$/.exec(lines[i]);
+    if (!m) continue;
+    const [, key, rest] = m;
+    const block = /^([>|])([+-]?)\s*$/.exec(rest);
+    if (block) {
+      const body = [];
+      while (i + 1 < lines.length && (/^\s+\S/.test(lines[i + 1]) || lines[i + 1].trim() === '')) body.push(lines[++i].trim());
+      out[key] = block[1] === '>'
+        ? body.join('\n').split(/\n{2,}/).map((p) => p.split('\n').join(' ')).join('\n').trim()
+        : body.join('\n').trim();
+      continue;
+    }
+    const list = /^\[(.*)\]$/.exec(rest.trim());
+    if (list) { out[key] = list[1].split(',').map((s) => s.trim().replace(/^(['"])(.*)\1$/, '$2')).filter(Boolean); continue; }
+    out[key] = rest.trim().replace(/^(['"])([\s\S]*)\1$/, '$2');
+  }
+  return out;
+}
+
+function readFrontmatter(skillMd) {
+  try { return parseFrontmatter(fs.readFileSync(skillMd, 'utf8')); } catch { return {}; }
+}
+
+// The description a SKILL.md gives, for the adoption walkthrough (task 1004073).
 function readDescription(skillMd) {
-  try {
-    const text = fs.readFileSync(skillMd, 'utf8');
-    const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
-    if (!fm) return '';
-    const line = fm[1].split(/\r?\n/).find((l) => /^description:\s*/.test(l));
-    if (!line) return '';
-    return line.replace(/^description:\s*/, '').replace(/^(['"])([\s\S]*)\1$/, '$2').trim();
-  } catch { return ''; }
+  const d = readFrontmatter(skillMd).description;
+  return typeof d === 'string' ? d : '';
 }
 
+// The optional PEOPLE-FACING fields (task 1004073). `description` is written to
+// be MATCHED by a model, so a skill's author may also say, for the person
+// deciding whether to turn it on: what it does (`plain`), when to reach for it
+// (`reach-for`) and what it costs (`cost`). Claude Code ignores keys it does not
+// know, as it already does `requires:`.
+const PEOPLE_KEYS = { plain: 'plain', 'reach-for': 'reachFor', cost: 'cost' };
+
 function collect(out, dir, source) {
   for (const name of listDirs(dir)) {
     if (!SKILL_NAME_RE.test(name) || out.has(name)) continue;
     const md = path.join(dir, name, 'SKILL.md');
     if (!fs.existsSync(md)) continue;
-    out.set(name, { name, description: readDescription(md), source });
+    const fm = readFrontmatter(md);
+    const entry = { name, description: typeof fm.description === 'string' ? fm.description : '', source };
+    for (const [key, field] of Object.entries(PEOPLE_KEYS)) if (typeof fm[key] === 'string' && fm[key]) entry[field] = fm[key];
+    if (Array.isArray(fm.requires) && fm.requires.length) entry.requires = fm.requires;
+    out.set(name, entry);
   }
 }
 
+// ONE SKILL, AS A PERSON DECIDING ABOUT IT READS IT (task 1004073; ADR 0310 §3:
+// "what it does, when its author reaches for it, what it costs"). Pure: takes an
+// installedSkills() entry and returns the three answers plus what the skill
+// needs. An author's own people-facing field always wins; without one each
+// answer is derived from the model-facing description, and `derived` says so,
+// so the walkthrough can be honest that the words were not written for them.
+//
+// The rank note is kept apart on purpose: enabling a skill GRANTS NOTHING
+// (ADR 0310 §1), so a Metic-only skill stays Metic-only after you turn it on,
+// and the person should be told that before they choose it, not after.
+function explainSkill(entry) {
+  const e = entry || {};
+  const desc = String(e.description || '').replace(/\s+/g, ' ').trim();
+  const cut = desc.search(/\bTriggers?:/i);
+  let does = (cut >= 0 ? desc.slice(0, cut) : desc).trim();
+  const triggers = cut >= 0 ? desc.slice(cut).replace(/^Triggers?:\s*/i, '') : '';
+
+  const rankMatch = /\b(Metic\+|Archon)[- ]only\b\.?/i.exec(does);
+  const rank = rankMatch ? (/archon/i.test(rankMatch[1]) ? 'archon' : 'metic') : null;
+  if (rankMatch) does = does.replace(rankMatch[0], '').replace(/\s{2,}/g, ' ').trim();
+
+  const quoted = [...triggers.matchAll(/"([^"]+)"/g)].map((m) => m[1].trim());
+  const commands = quoted.filter((q) => q.startsWith('/'));
+  const phrases = quoted.filter((q) => !q.startsWith('/'));
+  const otherwise = /\bor\s+(?!")([^"]+?)\.?$/i.exec(triggers);
+
+  let reachFor = e.reachFor || '';
+  if (!reachFor && (phrases.length || otherwise)) {
+    const said = phrases.slice(0, 3).map((p) => `“${p}”`).join(', ');
+    reachFor = [said && `When you would say something like ${said}`, otherwise && otherwise[1].trim()]
+      .filter(Boolean).join(' — or ');
+    reachFor = reachFor.charAt(0).toUpperCase() + reachFor.slice(1);
+    if (!/[.!?]$/.test(reachFor)) reachFor += '.';
+  }
+
+  let cost = e.cost || '';
+  if (!cost) {
+    const readOnly = /\bread-only\b|\bchanges nothing\b/i.test(desc);
+    const paid = /\bpaid\b/i.test(desc);
+    if (readOnly && paid) cost = 'Read-only as it normally runs, but its author flags a paid option — check before you use that one. Otherwise it uses your session like any other request.';
+    else if (readOnly) cost = 'Read-only: it looks things up and changes nothing. It uses your session like any other request.';
+    else if (paid) cost = 'Has a paid step — its author flags one in the description. Otherwise it uses your session like any other request.';
+    else cost = 'Its author has not written down what it costs. Running it uses your session like any other request.';
+  }
+
+  return {
+    name: e.name,
+    source: e.source || null,
+    does: e.plain || does,
+    reachFor,
+    cost,
+    commands,
+    needs: Array.isArray(e.requires) ? e.requires : [],
+    rank,
+    derived: { does: !e.plain, reachFor: !e.reachFor, cost: !e.cost },
+  };
+}
+
 /**
  * The skills this instance has: Map name -> { name, description, source }.
  * First root wins on a duplicate name (core, then instance, then modules), the
@@ -91,4 +187,4 @@ function installedSkillsCached(opts, now = Date.now()) {
 }
 function _resetCache() { cached = null; }
 
-module.exports = { SKILL_NAME_RE, installedSkills, installedSkillsCached, readDescription, _resetCache };
+module.exports = { SKILL_NAME_RE, installedSkills, installedSkillsCached, readDescription, parseFrontmatter, explainSkill, _resetCache };

package/modules/specialities/specialities.js

@@ -18,8 +18,10 @@
 //                                  OFFERS skills (`skills`), each adopter's ENABLED set
 //                                  starts empty (`enabled_skills`), and only a skill this
 //                                  instance has may be named (skills.js). The walkthrough
-//                                  that fills the enabled set is task 1004073; the session
-//                                  line naming it is task 1004074. Naming a skill grants
+//                                  that fills the enabled set was built in task 1004073
+//                                  (GET /specialities/:id/skills + the hall's settings
+//                                  panel); the session line naming it is task 1004074.
+//                                  Naming a skill grants
 //                                  nothing.
 // The genuinely new part is the knowledge bundle, which is why the migration adds
 // tables for it and this file carries the rules over them.

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.2",
+  "version": "1.20.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.20.2",
+      "version": "1.20.3",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.2",
+  "version": "1.20.3",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -8052,5 +8052,11 @@
       "id": "1003631",
       "text": "Closed a small consistency gap in the hall's needs-attention inbox: one link is now escaped like all the others. No visible change."
     }
+  ],
+  "1.20.3": [
+    {
+      "id": "1004073",
+      "text": "Adopting a speciality now walks you through its skills one at a time: what each does, when you'd use it, and what it costs, and you choose on or off for each before seeing the next. Nothing is switched on unless you choose it."
+    }
   ]
 }

package/scripts/hall-preview/server.js

@@ -160,6 +160,10 @@ const CANNED_WRITES = [
   // sent-back lines the artboard draws render too.
   ['POST', /^copy-desk\/pages\/[a-z0-9-]+:[a-z0-9-]+\/approve$/, 'copy-desk__pages__approve.post'],
   ['POST', /^copy-desk\/pages\/[a-z0-9-]+:[a-z0-9-]+\/send-back$/, 'copy-desk__pages__send-back.post'],
+  // a speciality's adopt and the walkthrough's save (task 1004073), so adopting
+  // opens the skills walkthrough and its recap can save in the harness.
+  ['POST', /^specialities\/\d+\/adopt$/, 'specialities__9__adopt.post'],
+  ['PUT', /^specialities\/\d+\/skills$/, 'specialities__9__skills.put'],
 ];
 
 // A DATE THAT ROTS CANNOT DEMO AN AGE SIGNAL (task 1004041). The help-request

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.20.2'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.20.3'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/speciality_skills.mjs

@@ -58,6 +58,46 @@ await test('the real tree resolves: the core ships skills a speciality can offer
   assert.ok(got.has('recall') && got.has('status'), 'core skills are found in this checkout');
 });
 
+await test('a FOLDED description (`>-`) is read as its text, not as the fold marker (task 1004073)', () => {
+  const fm = skills.parseFrontmatter('---\nname: x\ndescription: >-\n  One line\n  and the next.\nrequires: [gh, droplet-ssh]\ncost: "Free."\n---\nbody');
+  assert.equal(fm.description, 'One line and the next.');
+  assert.deepEqual(fm.requires, ['gh', 'droplet-ssh']);
+  assert.equal(fm.cost, 'Free.');
+  assert.equal(skills.parseFrontmatter('---\ndescription: |\n  a\n  b\n---\n').description, 'a\nb', 'a literal block keeps its lines');
+  assert.deepEqual(skills.parseFrontmatter('no frontmatter'), {});
+});
+
+await test('every skill in the real tree reads a real description — none is a bare fold marker', () => {
+  const got = skills.installedSkills({ coreRoot: ROOT, isModuleEnabled: () => false });
+  const bad = [...got.values()].filter((s) => !s.description || /^[>|][+-]?$/.test(s.description)).map((s) => s.name);
+  assert.deepEqual(bad, [], `these would teach nothing in the walkthrough: ${bad.join(', ')}`);
+});
+
+await test('explainSkill splits a model-facing description into what it does, when, and what it costs', () => {
+  const e = skills.explainSkill({
+    name: 'goal-review', source: 'core',
+    description: 'Walk the review queue. Read-only. Metic+ only. Triggers: "/goal-review", "review goals", "confirm criteria", or a scheduled run.',
+    requires: ['gh'],
+  });
+  assert.equal(e.does, 'Walk the review queue. Read-only.', 'the trigger list and the rank note are not part of what it does');
+  assert.equal(e.rank, 'metic', 'the rank is kept apart: enabling a skill grants nothing');
+  assert.deepEqual(e.commands, ['/goal-review']);
+  assert.match(e.reachFor, /“review goals”, “confirm criteria”.*a scheduled run/);
+  assert.match(e.cost, /^Read-only/);
+  assert.deepEqual(e.needs, ['gh']);
+  assert.deepEqual(e.derived, { does: true, reachFor: true, cost: true });
+});
+
+await test('explainSkill prefers the author\'s people-facing words and says when it had to guess', () => {
+  const e = skills.explainSkill({ name: 'x', description: 'Model text. Triggers: "/x".', plain: 'Plain words.', cost: 'About a dollar.' });
+  assert.equal(e.does, 'Plain words.');
+  assert.equal(e.cost, 'About a dollar.');
+  assert.deepEqual(e.derived, { does: false, reachFor: true, cost: false });
+  const unknown = skills.explainSkill({ name: 'y', description: 'Does a thing.' });
+  assert.match(unknown.cost, /has not written down what it costs/, 'an unknown cost is said plainly, never invented');
+  assert.match(skills.explainSkill({ name: 'z', description: 'Read-only check. --probe runs a paid calibration.' }).cost, /paid option/);
+});
+
 await test('an unreadable root contributes nothing rather than throwing', () => {
   const got = skills.installedSkills({ coreRoot: path.join(os.tmpdir(), 'no-such-root-' + Date.now()), isModuleEnabled: () => { throw new Error('boom'); } });
   assert.equal(got.size, 0);
@@ -146,7 +186,12 @@ db.setEnabledSkills = async (b, s, list) => (store.adoption ? { ...store.adoptio
 db.createSpeciality = async (row) => { store.created = row; return { id: 10, ...row }; };
 db.updateSpeciality = async (id, patch) => { store.updated = patch; return { ...store.speciality, ...patch }; };
 db.countTraining = async () => ({ documentCount: 0, learningCount: 0 });
-skills.installedSkillsCached = () => new Map([['recall', {}], ['status', {}], ['costing', {}]]);
+skills.installedSkillsCached = () => new Map([
+  ['recall', { name: 'recall', description: 'Search what the project knows. Read-only. Triggers: "/recall", "what do we know about X".', source: 'core' }],
+  ['status', { name: 'status', description: 'Roll up a version.', source: 'core' }],
+  ['costing', { name: 'costing', description: 'Price a thing.', source: 'module:econ' }],
+]);
+db.listAdoptions = async () => (store.adoption ? [{ id: 9, active: store.adoption.active, enabled_skills: store.adoption.enabled_skills }] : []);
 api.requireBuilder = (req, res, next) => { req.builder = { id: 1, rank: 'metic' }; next(); };
 api.enabledDisciplines = () => ['ideator', 'engineer', 'artist'];
 
@@ -187,6 +232,36 @@ try {
     store.speciality.skills = ['recall', 'status'];
   });
 
+  await test('GET /specialities/:id/skills explains each OFFERED skill for the walkthrough, and the caller\'s own set', async () => {
+    store.adoption = null;
+    store.speciality.skills = ['recall', 'gone-now'];
+    const r = await call('GET', '/specialities/9/skills');
+    assert.equal(r.status, 200, JSON.stringify(r.body));
+    assert.equal(r.body.adopted, false);
+    assert.deepEqual(r.body.enabled, []);
+    assert.deepEqual(r.body.skills.map((s) => s.name), ['recall', 'gone-now'], 'the offered set, in its order — not every installed skill');
+    const recall = r.body.skills[0];
+    assert.equal(recall.installed, true);
+    assert.equal(recall.does, 'Search what the project knows. Read-only.');
+    assert.match(recall.reachFor, /what do we know about X/);
+    assert.match(recall.cost, /^Read-only/);
+    assert.deepEqual(r.body.skills[1], { name: 'gone-now', installed: false }, 'a skill removed since is named, not explained or offered');
+
+    store.adoption = { builder_id: 1, speciality_id: 9, active: true, enabled_skills: ['recall'] };
+    const held = await call('GET', '/specialities/9/skills');
+    assert.equal(held.body.adopted, true);
+    assert.deepEqual(held.body.enabled, ['recall']);
+    store.speciality.skills = ['recall', 'status'];
+  });
+
+  await test('GET /specialities/:id/skills is 404 for a speciality the caller cannot see', async () => {
+    const saved = store.speciality;
+    store.speciality = { ...saved, owner_builder_id: 2, visibility: 'private' };
+    const r = await call('GET', '/specialities/9/skills');
+    assert.equal(r.status, 404);
+    store.speciality = saved;
+  });
+
   await test('PUT /specialities/:id/skills needs an active adoption', async () => {
     store.adoption = null;
     const r = await call('PUT', '/specialities/9/skills', { enabled_skills: ['recall'] });