@bongos/core 1.20.1 → 1.20.3

package/modules/hall-ui/public/settings-specialities.js

@@ -24,7 +24,9 @@
   const { escapeHtml, $ } = window.OTB;
   const toast = (msg) => window.OTB.toast(msg);
 
-  const state = { rows: [], suggestions: [], openId: null, busy: false };
+  // `walk` is the skills walkthrough in progress, or null (task 1004073):
+  // { id, data, step, decisions, saving }. See walkHtml below.
+  const state = { rows: [], suggestions: [], openId: null, busy: false, walk: null };
 
   const el = (id) => document.getElementById(id);
   const statusLine = (msg) => { const s = el('specialities-status'); if (s) s.textContent = msg || ''; };
@@ -73,10 +75,148 @@
       </details>`;
   }
 
+  // ── THE SKILLS WALKTHROUGH (task 1004073; ADR 0310 §3) ────────────────────
+  //
+  // The owner's ruling: an adopted speciality's skills start OFF, "and you
+  // should walk through what comes with each, people need to learn the system".
+  // So this is deliberately NOT a list of checkboxes. It shows ONE skill at a
+  // time — what it does, when to reach for it, what it costs — and moves on only
+  // once the person has decided about that one. There is no "turn them all on"
+  // and no skip: the bar is that someone who finishes can say what each skill
+  // does, and a control that decides without reading defeats it.
+  //
+  // Nothing is written until the recap's "Save my choices", and that sends the
+  // WHOLE set (PUT replaces it), so walking away half-way leaves every skill off —
+  // the default the ruling asked for. Turning a skill on grants nothing: a
+  // rank-gated skill stays rank-gated, and the step says so before you choose.
+
+  const walkSteps = (w) => (w.data.skills || []).filter((k) => k.installed);
+
+  const RANK_COPY = {
+    metic: 'Only builders of Metic rank or above can run it. Turning it on here does not change that.',
+    archon: 'Only the project owner (Archon) can run it. Turning it on here does not change that.',
+  };
+
+  async function openWalk(id) {
+    try {
+      const data = await call('GET', `/specialities/${id}/skills`);
+      if (!data) return;
+      if (!walkSteps({ data }).length) { toast('This speciality offers no skills to choose.'); return; }
+      state.walk = { id: String(id), data, step: 0, decisions: {}, saving: false };
+      state.openId = null;
+      render();
+      focusWalk();
+    } catch (err) { statusLine(`Could not load its skills — ${err.message}`); }
+  }
+
+  // Each step replaces the panel's contents, so focus goes to the new heading —
+  // otherwise a keyboard or screen-reader user is left on a button that no
+  // longer exists. Focus only; nothing animates.
+  function focusWalk() {
+    const h = document.querySelector('.skill-walk [data-walk-focus]');
+    if (h) h.focus();
+  }
+
+  function stepHtml(w, k, i, total) {
+    const was = w.data.enabled.includes(k.name);
+    const decided = w.decisions[k.name];
+    const commands = (k.commands || []).length
+      ? ` You can also start it yourself by typing <code>${escapeHtml(k.commands[0])}</code>.` : '';
+    const guessed = k.derived && (k.derived.does || k.derived.cost)
+      ? '<p class="prow__hint skill-walk__note">These words come from the skill’s own description, which was written for Claude to recognise rather than for you to read — so a term may go unexplained.</p>'
+      : '';
+    return `
+      <p class="skill-walk__progress">Skill ${i + 1} of ${total} in ${escapeHtml(w.data.speciality.name)}</p>
+      <h4 class="skill-walk__name" tabindex="-1" data-walk-focus>${escapeHtml(k.name)}</h4>
+      <dl class="skill-walk__facts">
+        <dt>What it does</dt><dd>${escapeHtml(k.does || 'Its author gave no description.')}</dd>
+        <dt>When to reach for it</dt><dd>${escapeHtml(k.reachFor || 'Its author did not say.')}${commands}</dd>
+        <dt>What it costs</dt><dd>${escapeHtml(k.cost)}</dd>
+        ${(k.needs || []).length ? `<dt>What it needs on your machine</dt><dd>${k.needs.map((n) => `<code>${escapeHtml(n)}</code>`).join(', ')}</dd>` : ''}
+        ${k.rank && RANK_COPY[k.rank] ? `<dt>Who can run it</dt><dd>${RANK_COPY[k.rank]}</dd>` : ''}
+      </dl>
+      ${guessed}
+      ${was ? '<p class="prow__hint">You have this one on at the moment.</p>' : ''}
+      <div class="speciality-actions skill-walk__actions">
+        ${i > 0 ? '<button type="button" class="pbtn pbtn--quiet" data-walk="back">Back</button>' : ''}
+        <button type="button" class="pbtn" data-walk="off" aria-pressed="${decided === false}">Leave it off</button>
+        <button type="button" class="pbtn" data-walk="on" aria-pressed="${decided === true}">Turn it on</button>
+      </div>`;
+  }
+
+  function recapHtml(w, steps) {
+    const on = steps.filter((k) => w.decisions[k.name]).length;
+    const gone = (w.data.skills || []).filter((k) => !k.installed);
+    return `
+      <h4 class="skill-walk__name" tabindex="-1" data-walk-focus>Your choices for ${escapeHtml(w.data.speciality.name)}</h4>
+      <p class="prow__hint">${on} of ${steps.length} turned on. Each one, in a line:</p>
+      <ul class="skill-walk__recap">
+        ${steps.map((k) => `
+          <li>
+            <strong>${escapeHtml(k.name)}</strong>
+            <span class="speciality-badge${w.decisions[k.name] ? ' speciality-badge--on' : ''}">${w.decisions[k.name] ? 'on' : 'off'}</span>
+            <span class="prow__hint">${escapeHtml(firstSentence(k.does))}</span>
+          </li>`).join('')}
+      </ul>
+      ${gone.length ? `<p class="prow__hint">Also offered, but no longer on this project, so it cannot be turned on: ${gone.map((k) => `<code>${escapeHtml(k.name)}</code>`).join(', ')}.</p>` : ''}
+      <div class="speciality-actions skill-walk__actions">
+        <button type="button" class="pbtn pbtn--quiet" data-walk="restart">Go through them again</button>
+        <button type="button" class="pbtn pbtn--save" data-walk="save" ${w.saving ? 'disabled' : ''}>Save my choices</button>
+      </div>`;
+  }
+
+  function firstSentence(text) {
+    const t = String(text || '');
+    const m = /^(.+?[.!?])(\s|$)/.exec(t);
+    return m ? m[1] : t;
+  }
+
+  function walkHtml() {
+    const w = state.walk;
+    const steps = walkSteps(w);
+    const body = w.step < steps.length ? stepHtml(w, steps[w.step], w.step, steps.length) : recapHtml(w, steps);
+    return `<section class="skill-walk" aria-label="Choose the skills for ${escapeHtml(w.data.speciality.name)}">
+      ${body}
+      <button type="button" class="skill-walk__later" data-walk="close">Finish later — everything stays off until you save</button>
+    </section>`;
+  }
+
+  async function walkAct(action) {
+    const w = state.walk;
+    if (!w) return;
+    const steps = walkSteps(w);
+    if (action === 'close') { state.walk = null; render(); return; }
+    if (action === 'back') w.step = Math.max(0, w.step - 1);
+    if (action === 'restart') w.step = 0;
+    if ((action === 'on' || action === 'off') && w.step < steps.length) {
+      w.decisions[steps[w.step].name] = action === 'on';
+      w.step += 1;
+    }
+    if (action === 'save') {
+      w.saving = true;
+      render();
+      try {
+        const enabled = steps.filter((k) => w.decisions[k.name]).map((k) => k.name);
+        await call('PUT', `/specialities/${w.id}/skills`, { enabled_skills: enabled });
+        state.walk = null;
+        toast(`Saved — ${enabled.length} of ${steps.length} skill${steps.length === 1 ? '' : 's'} on.`);
+        await load();
+        return;
+      } catch (err) {
+        w.saving = false;
+        statusLine(`Could not save your choices — ${err.message}`);
+      }
+    }
+    render();
+    focusWalk();
+  }
+
   function cardHtml(s) {
     const trained = Number(s.documentCount || 0);
     const learned = Number(s.learningCount || 0);
     const open = String(state.openId) === String(s.id);
+    const offered = Array.isArray(s.skills) ? s.skills.length : 0;
+    const walking = state.walk && state.walk.id === String(s.id);
     return `
       <li class="prow speciality-card" data-id="${escapeHtml(String(s.id))}">
         <div class="prow__main">
@@ -91,15 +231,18 @@
             Trained on <strong>${trained}</strong> document${trained === 1 ? '' : 's'} you added
             · learned <strong>${learned}</strong> thing${learned === 1 ? '' : 's'} from your sessions
             · shared with: ${escapeHtml(VISIBILITY_COPY[s.visibility] || s.visibility || 'only you')}
+            ${offered ? `· offers <strong>${offered}</strong> skill${offered === 1 ? '' : 's'}${s.active ? `, <strong>${(s.enabled_skills || []).length}</strong> on for you` : ''}` : ''}
           </p>
         </div>
         <div class="prow__actions">
+          ${s.active && offered && !walking ? `<button type="button" class="btn btn--quiet" data-act="walk" data-id="${escapeHtml(String(s.id))}">Choose its skills</button>` : ''}
           ${s.mine ? `<button type="button" class="btn btn--quiet" data-act="train" data-id="${escapeHtml(String(s.id))}">${open ? 'Close' : 'Train'}</button>` : ''}
           ${s.active
             ? `<button type="button" class="btn btn--quiet" data-act="abandon" data-id="${escapeHtml(String(s.id))}">Stop using</button>`
             : `<button type="button" class="btn" data-act="adopt" data-id="${escapeHtml(String(s.id))}" ${s.adoptable ? '' : 'disabled'}>Use this</button>`}
         </div>
         ${open ? trainHtml(s) : ''}
+        ${walking ? walkHtml() : ''}
       </li>`;
   }
 
@@ -183,10 +326,18 @@
       ]);
       if (!cat) return;
       state.suggestions = (offered && offered.suggestions) || [];
-      const activeIds = new Set(((mine && mine.adoptions) || []).filter((a) => a.active).map((a) => String(a.id)));
-      state.rows = ((cat && cat.specialities) || []).map((s) => ({ ...s, active: activeIds.has(String(s.id)) }));
+      const active = new Map(((mine && mine.adoptions) || []).filter((a) => a.active).map((a) => [String(a.id), a]));
+      state.rows = ((cat && cat.specialities) || []).map((s) => {
+        const a = active.get(String(s.id));
+        return { ...s, active: !!a, enabled_skills: (a && a.enabled_skills) || [] };
+      });
       render();
       statusLine('');
+      // The section ships `hidden`, like every settings panel, and is revealed
+      // once its reads answer. Nothing revealed this one until task 1004073, so
+      // the panel — and adoption with it — was unreachable from the hall.
+      const section = el('specialities-scroll');
+      if (section) section.hidden = false;
     } catch (err) {
       statusLine(`Could not load specialities — ${err.message}`);
     }
@@ -197,8 +348,18 @@
     state.busy = true;
     try {
       if (action === 'adopt') { await call('POST', `/specialities/${id}/adopt`); toast('Using this speciality.'); }
-      if (action === 'abandon') { await call('POST', `/specialities/${id}/abandon`); toast('Stopped using it.'); }
+      if (action === 'abandon') {
+        await call('POST', `/specialities/${id}/abandon`);
+        toast('Stopped using it.');
+        if (state.walk && state.walk.id === String(id)) state.walk = null;
+      }
       await load();
+      // Adopting is the moment the ruling is about: a speciality that offers
+      // skills opens straight into the walkthrough, with every one still off.
+      if (action === 'adopt') {
+        const row = state.rows.find((s) => String(s.id) === String(id));
+        if (row && Array.isArray(row.skills) && row.skills.length) await openWalk(id);
+      }
     } catch (err) {
       statusLine(err.message);
     } finally {
@@ -221,10 +382,13 @@
     const host = el('specialities-rows');
     if (host) {
       host.addEventListener('click', (e) => {
+        const walkBtn = e.target.closest('button[data-walk]');
+        if (walkBtn) { walkAct(walkBtn.dataset.walk); return; }
         const btn = e.target.closest('button[data-act]');
         if (!btn) return;
         const { act: action, id } = btn.dataset;
-        if (action === 'train') { state.openId = String(state.openId) === String(id) ? null : id; render(); return; }
+        if (action === 'walk') { openWalk(id); return; }
+        if (action === 'train') { state.openId = String(state.openId) === String(id) ? null : id; state.walk = null; render(); return; }
         act(action, id);
       });
 

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.1",
+  "version": "1.20.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.20.1",
+      "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.1",
+  "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

@@ -8046,5 +8046,17 @@
       "id": "1004368",
       "text": "CI checks were failing on every change because of a newly published security flaw in a networking library; updating it made the checks pass again so approved work can land."
     }
+  ],
+  "1.20.2": [
+    {
+      "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.1'; // 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/rot_inbox.mjs

@@ -630,3 +630,11 @@ test('acting on a rot line refreshes the ROT slice, not the goals list', () => {
   assert.match(GOAL_INBOX_SRC, /ROT_TOASTS\[verb\] \|\| 'Done\.', loadRot\)/,
     'refreshing the wrong slice leaves the acted-on row sitting there — the task-1003066 lesson');
 });
+
+test('rotRowHtml escapes the row href like every sibling field (task 1003631)', () => {
+  const start = GOAL_INBOX_SRC.indexOf('function rotRowHtml');
+  const body = GOAL_INBOX_SRC.slice(start, GOAL_INBOX_SRC.indexOf('\n  }\n', start));
+  assert.ok(start > 0, 'rotRowHtml exists');
+  assert.match(body, /href="\$\{escapeHtml\(href\)\}"/, 'href goes through escapeHtml');
+  assert.doesNotMatch(body, /href="\$\{href\}"/, 'no raw href interpolation');
+});