Per-operation 'Complete this operation' + default back to live apis.io

Prefer working the live surface operation by operation. Default example is apis.io (live) again;
the bulk target roadmap is demoted to a reference example. Each operation's ✨ now leads with
'Complete this operation' — one precise Claude pass returning the tool + prompts + resources +
skill for THAT operation together (scoping to one op makes each part precise and consistent),
rendered as four add-able sections. Per-kind suggestions remain below it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: apievangelist

src/main.ts

@@ -15,17 +15,17 @@ import { buildExperience, deriveSurface, computeCoverage, type ExperienceModel,
 import { renderExperience } from './render';
 import { initEngage } from './engage';
 import { initSettings, openSettings, getToken } from './settings';
-import { suggest, applySuggestion, describe, type SuggestKind } from './suggest';
+import { suggest, applySuggestion, describe, completeOperation, type SuggestKind, type Suggestion } from './suggest';
 import { downloadBundle } from './bundle';
 import { esc, escAttr } from './ui';
 
 // `src` is what we actually fetch (must be same-origin or CORS-enabled); `show` is the
 // human label. apis.io/apis.json has no CORS header, so we bundle it locally and let the
 // tool fetch its OpenAPI from githubusercontent (which does allow cross-origin).
 const DEFAULTS = [
-  { label: 'APIs.io — target surface', src: './examples/apis-io-target.json', show: 'apis.io roadmap', blurb: 'The proposed robust API → MCP → Agent-Skill buildout for apis.io — 54 operations, 11 prompts, 12 resources, 10 skills. A roadmap, not the live contract.' },
-  { label: 'APIs.io — live', src: './examples/apis-io.json', show: 'apis.io/apis.json', blurb: 'The API → MCP → Agent-Skill surface deployed on apis.io today: discovery free, synthesis Pro.' },
+  { label: 'APIs.io', src: './examples/apis-io.json', show: 'apis.io/apis.json', blurb: 'The live API → MCP → Agent-Skill surface of apis.io. Work it operation by operation — the ✨ on each row completes that one operation precisely.' },
   { label: 'API Evangelist', src: 'https://apievangelist.com/apis.yml', show: 'apievangelist.com/apis.yml', blurb: 'The API Evangelist network index.' },
+  { label: 'APIs.io — target (roadmap)', src: './examples/apis-io-target.json', show: 'apis.io roadmap', blurb: 'A bulk proposed buildout, for reference — prefer completing operations one at a time on the live surface above.' },
 ];
 
 let current: ApisDoc | null = null;
@@ -195,7 +195,9 @@ function openOpMenu(anchor: HTMLElement, op: ExpOperation): void {
   const el = document.createElement('div');
   el.className = 'op-menu';
   el.innerHTML = `
-    <div class="op-menu-h">Suggest for ${esc(op.method)} ${esc(op.path)}</div>
+    <div class="op-menu-h">Complete ${esc(op.method)} ${esc(op.path)}</div>
+    <button data-complete="1"><strong>✨ Complete this operation</strong><span class="op-menu-sub">tool + prompts + resources + skill, in one pass</span></button>
+    <div class="op-menu-div"></div>
     <button data-k="tool">⚙ MCP tool</button>
     <button data-k="prompt">◇ MCP prompt</button>
     <button data-k="resource">▤ MCP resource</button>
@@ -204,12 +206,82 @@ function openOpMenu(anchor: HTMLElement, op: ExpOperation): void {
   document.body.appendChild(el);
   const r = anchor.getBoundingClientRect();
   el.style.top = `${window.scrollY + r.bottom + 4}px`;
-  el.style.left = `${window.scrollX + Math.min(r.left, window.innerWidth - 220)}px`;
+  el.style.left = `${window.scrollX + Math.min(r.left, window.innerWidth - 240)}px`;
+  el.querySelector<HTMLButtonElement>('button[data-complete]')!.addEventListener('click', () => { closeOpMenu(); runComplete(op); });
   el.querySelectorAll<HTMLButtonElement>('button[data-k]').forEach((b) =>
     b.addEventListener('click', () => { closeOpMenu(); runSuggest(b.dataset.k as SuggestKind, op); }));
   opMenuEl = el;
 }
 
+async function runComplete(op: ExpOperation): Promise<void> {
+  const token = getToken();
+  if (!token) { openSettings(); return; }
+  const exp = targetApi();
+  if (!exp) { alert('Load an API that has an OpenAPI first.'); return; }
+  completeModal(op, exp, 'loading', null);
+  try {
+    const res = await completeOperation(exp, op, token);
+    completeModal(op, exp, 'ready', res);
+  } catch (e) {
+    completeModal(op, exp, 'error', null, e instanceof Error ? e.message : String(e));
+  }
+}
+
+let cModal: HTMLElement | null = null;
+function completeModal(op: ExpOperation, exp: ExpApi, state: string, res: Awaited<ReturnType<typeof completeOperation>> | null, err = ''): void {
+  if (!cModal) {
+    cModal = document.createElement('div');
+    cModal.className = 'modal suggest-modal';
+    document.body.appendChild(cModal);
+    cModal.addEventListener('click', (e) => { if (e.target === cModal) cModal!.hidden = true; });
+  }
+  const section = (title: string, kind: SuggestKind, items: Suggestion[]) => {
+    if (!items.length) return `<div class="cx-sec"><div class="cx-h">${esc(title)}</div><p class="muted cx-empty">Nothing suggested — this part looks covered.</p></div>`;
+    const hasTier = kind !== 'skill';
+    return `<div class="cx-sec"><div class="cx-h">${esc(title)}</div>${items.map((s, i) => {
+      const def = s.tier || (kind === 'tool' && op.tier === 'pro' ? 'pro' : 'free');
+      return `<div class="sug-item" data-kind="${kind}" data-i="${i}">
+        <div class="sug-text"><code>${esc(describe(kind, s))}</code>${s.description ? `<span class="sug-desc">${esc(s.description)}</span>` : ''}</div>
+        <div class="sug-actions">
+          ${hasTier ? `<span class="sug-tier"><button type="button" class="tglt ${def === 'free' ? 'on' : ''}" data-t="free">Free</button><button type="button" class="tglt ${def === 'pro' ? 'on' : ''}" data-t="pro">Pro</button></span>` : ''}
+          <button class="btn sug-add">+ Add</button>
+        </div>
+      </div>`; }).join('')}</div>`;
+  };
+  const body = state === 'loading'
+    ? `<div class="loading"><div class="spinner"></div><p>Completing <code>${esc(op.method)} ${esc(op.path)}</code>…</p></div>`
+    : state === 'error'
+      ? `<div class="error-box"><p>${esc(err)}</p></div>`
+      : `<p class="sug-intro">Precise proposal for <code>${esc(op.method)} ${esc(op.path)}</code> — add the parts you want; each edits the in-memory OpenAPI and re-renders.</p>
+         ${section('⚙ MCP tool', 'tool', res!.tools)}
+         ${section('◇ MCP prompts', 'prompt', res!.prompts)}
+         ${section('▤ MCP resources', 'resource', res!.resources)}
+         ${section('✦ Agent Skill', 'skill', res!.skills)}`;
+  cModal.innerHTML = `<div class="modal-card suggest-card">
+      <div class="modal-head"><span>✨ Complete ${esc(op.method)} ${esc(op.path)}</span><button type="button" class="sug-close" aria-label="Close">×</button></div>
+      <div class="suggest-body">${body}</div>
+    </div>`;
+  cModal.hidden = false;
+  cModal.querySelector('.sug-close')!.addEventListener('click', () => { cModal!.hidden = true; });
+  cModal.querySelectorAll<HTMLButtonElement>('.tglt').forEach((t) => t.addEventListener('click', () => {
+    const wrap = t.closest('.sug-tier')!; wrap.querySelectorAll('.tglt').forEach((x) => x.classList.remove('on')); t.classList.add('on');
+  }));
+  if (res) cModal.querySelectorAll<HTMLButtonElement>('.sug-add').forEach((btn) => btn.addEventListener('click', () => {
+    const item = btn.closest<HTMLElement>('.sug-item')!;
+    const kind = item.dataset.kind as SuggestKind;
+    const list = kind === 'tool' ? res.tools : kind === 'prompt' ? res.prompts : kind === 'resource' ? res.resources : res.skills;
+    const s = { ...list[Number(item.dataset.i)] };
+    const onTier = item.querySelector<HTMLElement>('.tglt.on');
+    if (onTier) s.tier = onTier.dataset.t as 'free' | 'pro';
+    applySuggestion(kind, exp, s, op);
+    deriveSurface(exp);
+    if (model) model.coverage = computeCoverage(model.apis);
+    editCount++;
+    reRender();
+    btn.textContent = '✓ Added'; btn.disabled = true;
+  }));
+}
+
 async function runSuggest(kind: SuggestKind, op?: ExpOperation): Promise<void> {
   const token = getToken();
   if (!token) { openSettings(); return; }

src/style.css

@@ -484,3 +484,13 @@ div.resp { display: flex; align-items: center; gap: 0.6rem; padding: 0.4rem 0.6r
 .sug-tier .tglt + .tglt { border-left: 1px solid var(--line); }
 .sug-tier .tglt.on[data-t=free] { background: color-mix(in srgb, var(--ok) 15%, transparent); color: var(--ok); }
 .sug-tier .tglt.on[data-t=pro] { background: var(--accent-soft); color: var(--accent); }
+
+/* Complete-operation menu item + modal sections */
+.op-menu button[data-complete] { display: flex; flex-direction: column; align-items: flex-start; gap: .1rem; }
+.op-menu button[data-complete] strong { color: var(--accent); }
+.op-menu-sub { font-size: .68rem; color: var(--muted); }
+.op-menu-div { height: 1px; background: var(--line-soft); margin: .1rem 0; }
+.cx-sec { margin-bottom: 1rem; }
+.cx-h { font-size: .75rem; font-weight: 700; text-transform: uppercase; letter-spacing: .3px; color: var(--brand); margin: 0 0 .4rem; padding-bottom: .25rem; border-bottom: 1px solid var(--line-soft); }
+.cx-empty { font-size: .82rem; margin: .2rem 0; }
+.cx-sec .sug-item { margin-bottom: .4rem; }

src/suggest.ts

@@ -87,6 +87,47 @@ Return ONLY the suggestions object.`;
   return (out.suggestions || []).slice(0, 8);
 }
 
+export interface CompleteResult { tools: Suggestion[]; prompts: Suggestion[]; resources: Suggestion[]; skills: Suggestion[]; }
+
+// Precise, operation-scoped pass: ask ONE question about a single operation and get a coherent
+// set across all four dimensions at once — the right tool, the prompts that would orchestrate it,
+// the resources it should back, and the skill it belongs to. Scoping to one op makes each part
+// precise (and mutually consistent) in a way per-kind suggestions can't be.
+export async function completeOperation(exp: ExpApi, op: ExpOperation, token: string): Promise<CompleteResult> {
+  const it = (props: Record<string, unknown>, required: string[]) =>
+    ({ type: 'object', additionalProperties: false, properties: props, required });
+  const schema = {
+    type: 'object', additionalProperties: false, required: ['tools', 'prompts', 'resources', 'skills'],
+    properties: {
+      tools: { type: 'array', items: it({ mcpTool: strT, description: strT, tier: tierEnum }, ['mcpTool', 'description']) },
+      prompts: { type: 'array', items: it({ name: strT, tier: tierEnum, description: strT }, ['name', 'tier', 'description']) },
+      resources: { type: 'array', items: it({ uri: strT, tier: tierEnum, description: strT }, ['uri', 'tier', 'description']) },
+      skills: { type: 'array', items: it({ name: strT, description: strT }, ['name', 'description']) },
+    },
+  };
+  const prompt = `Complete the DX/AX for exactly ONE operation. Propose precisely, and only what genuinely improves THIS operation — empty arrays are fine:
+  - tools: the MCP tool this operation should expose if it lacks a good one (0-1; leave empty if "tool" below is already right)
+  - prompts: MCP prompts that would orchestrate this operation's tool (0-3)
+  - resources: resources this operation should back / expose (0-2)
+  - skills: the single Agent Skill this operation belongs to (0-1; a short kebab-case slug)
+
+Focus operation:
+  ${op.method} ${op.path}  (id:${op.operationId || '?'}, tier:${op.tier}, tool:${op.mcpTool || '— none —'}, skill:${op.agentSkill || '— none —'})
+
+Full API surface for context (don't duplicate what exists; reuse existing tool/prompt/resource names where they'd apply):
+
+${context(exp)}
+
+Return ONLY the object.`;
+  const out = await callClaudeJSON<CompleteResult>({ token, system: getGuideSkill(), prompt, schema, maxTokens: 3000 });
+  return {
+    tools: (out.tools || []).slice(0, 2),
+    prompts: (out.prompts || []).slice(0, 4),
+    resources: (out.resources || []).slice(0, 3),
+    skills: (out.skills || []).slice(0, 2),
+  };
+}
+
 // A one-line human label for a suggestion in the picker.
 export function describe(kind: SuggestKind, s: Suggestion): string {
   if (kind === 'path') return `${s.method} ${s.path} → ${s.mcpTool} [${s.tier}]`;