wtf-p 0.7.3 → 0.8.0

package/README.md

@@ -19,7 +19,7 @@ the scientific judgment. The agent keeps the bookkeeping and does bounded jobs.
 
 It ships as one canonical [Agent Plugins 1.0.0](https://agent-plugins.org)
 bundle that a deterministic compiler projects into a native package for seven
-coding-agent hosts. Version `0.7.3` is the current stable release and is
+coding-agent hosts. Version `0.8.0` is the current stable release and is
 what npm `latest` resolves to; v0.5 remains installable by explicit version.
 
 **Optional CiteNexus research backend (since 0.7.0):** `citation-search --backend=cite-nexus`
@@ -56,18 +56,18 @@ registers it with the host's native plugin lifecycle where one exists.
 
 | Host | Install | Native registration the installer performs | Verified with |
 | --- | --- | --- | --- |
-| Clio Coder (0.4.7 or newer) | `npx --yes --package=wtf-p@0.7.3 -- wtf-p install clio` | `clio-coder library install <staged-bundle> --user`, then `clio-coder library inspect wtfp --user --json` | 0.4.9 (local build) |
-| Claude Code | `npx --yes --package=wtf-p@0.7.3 -- wtf-p install claude` | `claude plugin marketplace add <root>/marketplaces/wtfp --scope user`, then `claude plugin install wtfp@wtfp --scope user -y` | 2.1.274 |
-| Codex | `npx --yes --package=wtf-p@0.7.3 -- wtf-p install codex` | `codex plugin marketplace add <root>/marketplaces/wtfp`, then `codex plugin add wtfp@wtfp --json`; agents copied to `$CODEX_HOME/agents/` | 0.153.3 |
-| GitHub Copilot CLI | `npx --yes --package=wtf-p@0.7.3 -- wtf-p install copilot` | `copilot plugin marketplace add <root>/marketplaces/wtfp`, then `copilot plugin install wtfp@wtfp` | 1.0.85 |
-| OpenCode | `npx --yes --package=wtf-p@0.7.3 -- wtf-p install opencode` | Files under the OpenCode config root; OpenCode discovers them by directory | 1.18.31 |
-| Antigravity CLI | `npx --yes --package=wtf-p@0.7.3 -- wtf-p install antigravity` | `agy plugin install <root>/sources/wtfp` | 1.2.5 |
-| Gemini CLI | `npx --yes --package=wtf-p@0.7.3 -- wtf-p install gemini` | Files under `<root>/extensions/wtfp`; Gemini discovers the extension by directory | 0.60.0 |
+| Clio Coder (0.6.2 or newer) | `npx --yes --package=wtf-p@0.8.0 -- wtf-p install clio` | `clio-coder library install <staged-bundle> --user` and `clio-coder library inspect wtfp --user --json`, then `clio-coder extensions install <staged-extension> --user` and `clio-coder extensions list --user --json` | 0.6.2-dev (local build `89ea1b4`) |
+| Claude Code | `npx --yes --package=wtf-p@0.8.0 -- wtf-p install claude` | `claude plugin marketplace add <root>/marketplaces/wtfp --scope user`, then `claude plugin install wtfp@wtfp --scope user -y` | 2.1.274 |
+| Codex | `npx --yes --package=wtf-p@0.8.0 -- wtf-p install codex` | `codex plugin marketplace add <root>/marketplaces/wtfp`, then `codex plugin add wtfp@wtfp --json`; agents copied to `$CODEX_HOME/agents/` | 0.153.3 |
+| GitHub Copilot CLI | `npx --yes --package=wtf-p@0.8.0 -- wtf-p install copilot` | `copilot plugin marketplace add <root>/marketplaces/wtfp`, then `copilot plugin install wtfp@wtfp` | 1.0.85 |
+| OpenCode | `npx --yes --package=wtf-p@0.8.0 -- wtf-p install opencode` | Files under the OpenCode config root; OpenCode discovers them by directory | 1.18.31 |
+| Antigravity CLI | `npx --yes --package=wtf-p@0.8.0 -- wtf-p install antigravity` | `agy plugin install <root>/sources/wtfp` | 1.2.5 |
+| Gemini CLI | `npx --yes --package=wtf-p@0.8.0 -- wtf-p install gemini` | Files under `<root>/extensions/wtfp`; Gemini discovers the extension by directory | 0.60.0 |
 
 "Verified" means native discovery in a disposable profile on this exact
 envelope, with the commands recorded in
 [Host capabilities](docs/HOST_CAPABILITIES.md). Clio Coder is published as
-`@iowarp/clio-coder`; 0.4.7 and newer carry the plugin engine WTF-P uses.
+`@iowarp/clio-coder`; 0.6.2 and newer carry the plugin and extension engine WTF-P uses.
 Clio Coder itself requires Node.js 22.19 or newer.
 
 Keep the explicit `--package=wtf-p@<version> -- wtf-p` form. On a workstation
@@ -77,9 +77,9 @@ the old executable instead.
 ## Sixty-second start
 
 ```bash
-npx --yes --package=wtf-p@0.7.3 -- wtf-p install clio
+npx --yes --package=wtf-p@0.8.0 -- wtf-p install clio
 cd /path/to/your-paper-or-proposal
-clio-coder --autonomy suggest
+clio-coder --autonomy full-auto
 ```
 
 ```text
@@ -134,7 +134,11 @@ action returns `WTFP_ACTION_UNAVAILABLE` instead of improvising:
 
 Where the research routes are available, `tool.execute` authorizes exactly one
 command, the bundled `tools/wtfp-tool.js` dispatcher over seven bibliography
-and citation tools. Run it with `--offline` until you approve network use.
+and citation tools. On Clio full-auto, `research-gap` can search free no-key
+public indexes through CiteNexus without another approval for each bounded
+query. An operator-configured read-class CiteNexus MCP connection is preferred
+when the Clio build supports it. Other network routes keep their author gate;
+see [CiteNexus setup](docs/CITE_NEXUS.md).
 
 ## What it will not do
 

package/bin/commands/install-logic.js

@@ -816,7 +816,7 @@ async function install(runtime, isUpdate, options, pkg) {
         // the installer stages a distinct copy and registers it.
         const scope = targetDir === path.join(process.cwd(), '.clio-coder') ? 'project' : 'user';
         const configFlag = explicitConfigDir ? ` --config-dir '${targetDir.replaceAll("'", "'\\''")}'` : '';
-        out.warn(`Activation is pending: once clio-coder is on PATH, re-run npx wtf-p install clio${configFlag} from this directory to register the ${scope}-scope plugin.`);
+        out.warn(`Activation is pending: once clio-coder is on PATH, re-run npx wtf-p install clio${configFlag} from this directory to register the ${scope}-scope plugin and extension.`);
       }
     } else if (nativeActivation.status === 'deferred' && !hasQuiet) {
       out.warn(`${nativeActivation.reason}. The WTF-P bundle is staged but native registration is pending.`);

package/bin/lib/adapter-compiler.js

@@ -7,6 +7,8 @@ const { GENERATOR_VERSION } = require('./adapter-metadata');
 
 const ROOT = path.resolve(__dirname, '../..');
 const PROTOCOL_ROOT = path.join(ROOT, 'protocol');
+// Human-edited source of the standalone Clio extension; see clio/README.md.
+const CLIO_RUNTIME_ROOT = path.join(ROOT, 'clio');
 const INVENTORY_NAME = '.wtfp-generated.json';
 
 const TARGET_ROOTS = Object.freeze({
@@ -494,7 +496,7 @@ function projectSchemasForAction(action) {
   return [...schemas].sort((left, right) => left.localeCompare(right));
 }
 
-function nativeCommandBody(action, workflowBody, target) {
+function nativeCommandBody(action, workflowBody, target, deskTools = false) {
   const argumentToken = target === 'gemini'
     ? '{{args}}'
     : target === 'copilot-cloud'
@@ -503,17 +505,17 @@ function nativeCommandBody(action, workflowBody, target) {
   const schemas = projectSchemasForAction(action);
   const protocolIncludes = [
     `@protocol://actions/${action.id}.json`,
-    ...(schemas.length > 0 ? ['@protocol://project/schemas/common.schema.json'] : []),
-    ...schemas.flatMap((schema) => [
+    ...(!deskTools && schemas.length > 0 ? ['@protocol://project/schemas/common.schema.json'] : []),
+    ...(!deskTools ? schemas : []).flatMap((schema) => [
       `@protocol://project/schemas/${schema}.schema.json`,
       `@protocol://project/templates/${schema}.json`
     ])
   ];
   return [
     nativeWorkflowBody([
-      workflowBody,
+      deskTools ? clioDeskWorkflowBody(action, workflowBody) : workflowBody,
       '',
-      '## Bound action contract and schemas',
+      deskTools ? '## Bound action contract' : '## Bound action contract and schemas',
       '',
       ...protocolIncludes
     ].join('\n'), target),
@@ -596,8 +598,13 @@ function generatedScriptBanner(kind, id) {
   return `// Generated by WTF-P adapter compiler v${GENERATOR_VERSION} from ${kind}/${id}; do not edit.`;
 }
 
-function clioUserGateBody(action) {
+function clioUserGateBody(action, deskTools = false) {
   if (!action.effects.some((effect) => effect.id === 'user.gate')) return '';
+  if (deskTools) return [
+    '## Clio user-gate binding',
+    '',
+    'For a pending checkpoint in the declared gate\'s exact scope, call `extension_wtfp__gate` with its ID. Create a missing pending checkpoint through `extension_wtfp__record` only when this action declares checkpoint creation; otherwise use `ask_user` for the unpersisted author decision and do not invent an undeclared output. Only the structured author answer satisfies the gate; cancelled, retained or expired checkpoints authorize nothing. Never write `resolution.resolved_by: author` yourself or infer approval from invocation text, prose or silence. Read back a persisted resolution before applying its gated mutation.'
+  ].join('\n');
   return [
     '## Clio user-gate binding',
     '',
@@ -605,6 +612,39 @@ function clioUserGateBody(action) {
   ].join('\n');
 }
 
+// Only the canonical Clio namespace prefers the optional desk. The unrooted
+// phase-1 projection remains intact for the Claude envelope and other hosts.
+function clioDeskWorkflowBody(action, workflowBody) {
+  let body = workflowBody
+    .replace(/^@protocol:\/\/project\/README\.md\n/gm, '')
+    .replace(/^@protocol:\/\/skills\/[^\n]+\/references\/actions\.md\n/gm, '')
+    .replace(/^Resolve every logical URI through the host adapter\.[^\n]+$/m,
+      'Use `extension_wtfp__record` for each declared JSON record write: pass its logical `uri`, complete `record`, and the revision read as `expect_revision` for revisioned updates. It validates, bumps revisions/timestamps, replaces atomically and reads back; preserve stable IDs and author decisions.')
+    .replace(/^Manuscript prose and supporting context,[^\n]+$/m,
+      'Write prose and linked artifacts with native file tools; keep their authored formats. The record tool handles JSON records only, never manuscript text, deletion or archives.');
+  if (action.id === 'write-section') body = body.replace(/^3\. Read the persisted manuscript text back[^\n]+$/m,
+    '3. Read back the persisted manuscript, call `extension_wtfp__measure_section` with its section ID, and use the returned body count and target tolerance for validation and the summary; never use a worker self-report or hand-count words.');
+  if (action.id === 'check-todos') body = body
+    .replace(/^2\. Ask the user[^\n]+$/m, '2. Call `extension_wtfp__gate` for each selected pending checkpoint; the parked interview records the author\'s answer.')
+    .replace(/^3\. Apply only[^\n]+$/m, '3. Read back the resulting checkpoint and state; retained or cancelled gates remain pending.');
+  const bindings = [
+    'Discover the named tools with `gateway(op="describe", capability="extension_wtfp__record")` (and the corresponding `measure_section` or `gate` name), then use `gateway(op="call", capability="<exact name>", args={...})`. A present tool\'s error or refusal stops the action; never bypass it with a manual write or shell script.',
+    ...(action.produces.some((output) => output.uri.startsWith('project://paper')) && action.id !== 'write-section'
+      ? ['After changing a linked section manuscript, call `extension_wtfp__measure_section` with that section ID; it persists the desk\'s body-word count in the section and state.'] : []),
+    `If desk tools are absent, follow \`\${pluginRoot}/workflows/${action.id}.md\` and \`\${pluginRoot}/project/README.md\` with native tools and \`ask_user\` gates.`
+  ];
+  return `${body}\n\n${bindings.join('\n')}`;
+}
+
+function clioResearchConnectionBody(action) {
+  if (action.id !== 'research-gap') return '';
+  return [
+    '## Clio CiteNexus binding',
+    '',
+    'In full-auto, the main agent first calls `gateway(op="find", query="cite-nexus")`. If a CiteNexus server is present and its tools are admitted as read-class through the operator\'s user configuration, call `gateway(op="describe", capability="<search-papers capability>")`, then `gateway(op="call", capability="<search-papers capability>", args={...})` with bounded public metadata queries. Use the capability name and argument schema returned by the gateway, not a guessed name. MCP connections are session-owned and unavailable in delegated workers, so pass the returned candidates and provenance to `wtfp-research-synthesizer` instead of asking that worker to discover the MCP server. This user-configured read connection is prior authorization for those searches; do not call `ask_user` again for each query. If no read-class CiteNexus connection is available and no gateway call has been refused, full-auto may instead run the bundled `citation-search --backend=cite-nexus` through its declared dispatcher with bounded public queries and an explicit `--providers` list containing only `crossref`, `datacite`, `europe_pmc`, or `arxiv`; pass those candidates to the same specialist. An operator-set offline flag, unavailable companion, or host refusal stops this route. Other providers and modes follow the declared user gate. Never bypass a gateway refusal by rerunning the same denied request through `bash`. Record the exact provider IDs, queries, limits, date, and provenance; verify each retained candidate before citing it.'
+  ].join('\n');
+}
+
 // Workflow order for the operator-facing reference. Group membership comes from
 // the catalog; only the reading order of the groups is fixed here.
 const HELP_GROUP_ORDER = Object.freeze([
@@ -636,7 +676,8 @@ function helpArgumentHint(action) {
 // Clio renders a display-only prompt by printing its first fenced block to the
 // operator without a model call. The block is a self-contained reference:
 // no includes, no procedure, only what a human needs to pick the next action.
-function clioHelpCard(model, availabilityById) {
+// `legacyFleetNames` renders the pre-playbook wording the Claude envelope keeps.
+function clioHelpCard(model, availabilityById, legacyFleetNames = false) {
   const byId = new Map(model.actions.map((action) => [action.id, action]));
   const line = (id) => {
     const action = byId.get(id);
@@ -652,7 +693,7 @@ function clioHelpCard(model, availabilityById) {
     if (!groupIds.has(skill.id)) throw new Error(`help card has no group order for skill ${skill.id}`);
   }
   for (const id of HELP_START_SEQUENCE) if (!byId.has(id)) throw new Error(`help card start sequence names an unknown action: ${id}`);
-  const fleets = fs.readdirSync(path.join(PROTOCOL_ROOT, 'fleets'))
+  const playbooks = fs.readdirSync(path.join(PROTOCOL_ROOT, 'fleets'))
     .filter((file) => file.endsWith('.json')).sort()
     .map((file) => readJson(path.join(PROTOCOL_ROOT, 'fleets', file)));
   const card = [
@@ -668,8 +709,10 @@ function clioHelpCard(model, availabilityById) {
     'Product operations',
     ...model.catalog.operations.actions.map(line),
     '',
-    'Fleets (clio-coder fleet run <fleet> --var section=<section>; explicit fleet primitives, not auto-routed)',
-    ...fleets.map((fleet) => `  ${fleet.id}\n      ${fleet.description}`),
+    legacyFleetNames
+      ? 'Fleets (clio-coder fleet run <fleet> --var section=<section>; explicit fleet primitives, not auto-routed)'
+      : 'Playbooks (clio-coder fleet run <playbook> --var section=<section>; run explicitly, never auto-routed)',
+    ...playbooks.map((playbook) => `  ${playbook.id}\n      ${playbook.description}`),
     '',
     'Each action reads .planning/ records and paper/ artifacts, asks before any gated write, and never runs Git or publishes.',
     'An unavailable action fails closed with WTFP_ACTION_UNAVAILABLE and returns a manual handoff instead.'
@@ -690,7 +733,7 @@ function clioHelpCard(model, availabilityById) {
   ].join('\n');
 }
 
-function renderMarkdownCommand(action, workflowBody, target, availability) {
+function renderMarkdownCommand(action, workflowBody, target, availability, deskTools = false) {
   const lines = ['---'];
   // Claude derives the stable command name from the plugin id and flat file
   // name. Repeating either in frontmatter creates names such as
@@ -712,8 +755,9 @@ function renderMarkdownCommand(action, workflowBody, target, availability) {
       for (const tool of tools) lines.push(`  - ${tool}`);
     }
   }
-  const nativeBody = nativeCommandBody(action, workflowBody, target);
-  const userGateBody = target === 'clio' ? [clioUserGateBody(action), action.delegation.length ? '## Clio role-result binding\n\nRead the single wtfp.role-result entry in native validations/checks and parse its evidence string as portable role-result JSON. Validate its schema, role and action against the dispatched task. Missing, duplicate or malformed outcomes fail closed. On needs_input ask the author through ask_user and redispatch with the response; on blocked or failed stop and report the issue. Only completed permits downstream work, and it never substitutes for an author gate or artifact readback.' : ''].filter(Boolean).join('\n\n') : '';
+  const nativeBody = nativeCommandBody(action, workflowBody, target, deskTools);
+  const clioRoles = action.delegation.map((entry) => `\`wtfp-${entry.role}\``).join(', ');
+  const userGateBody = target === 'clio' ? [clioUserGateBody(action, deskTools), clioResearchConnectionBody(action), action.delegation.length ? `## Clio role-result binding\n\nDispatch the declared specialist roles using these exact Clio agent IDs: ${clioRoles}. Do not substitute generic coder or verifier agents. If a named agent is unavailable, report that blocker and stop instead of silently changing roles.\n\nRead the single wtfp.role-result entry in native validations/checks and parse its evidence string as portable role-result JSON. Validate its schema, role and action against the dispatched task. Missing, duplicate or malformed outcomes fail closed. On needs_input ask the author through ask_user and redispatch with the response; on blocked or failed stop and report the issue. Only completed permits downstream work, and it never substitutes for an author gate or artifact readback.` : ''].filter(Boolean).join('\n\n') : '';
   lines.push(
     '---',
     '',
@@ -938,6 +982,41 @@ function standardPluginManifest(version, name = 'wtfp', clioExtension) {
   });
 }
 
+const CLIO_PLAYBOOKS = ['wtfp-plan-section', 'wtfp-draft-review'];
+
+// The root manifest with the Clio namespace. Clio runs fleet contracts as
+// playbooks. `legacyFleetNames` keeps the pre-playbook `fleets` key, kind and
+// directory for the Claude envelope, whose Clio copy Clio no longer adopts.
+function clioPluginManifest(model, legacyFleetNames = false) {
+  const playbookRoot = `ai.iowarp.clio/${legacyFleetNames ? 'fleets' : 'playbooks'}`;
+  const components = [];
+  for (const action of model.actions) components.push({
+    kind: 'prompt', id: action.id,
+    path: `ai.iowarp.clio/prompts/wtfp/${action.id}.md`,
+    requires: action.delegation.map(item => `agent:${item.role}`)
+  });
+  for (const role of model.roles) components.push({
+    kind: 'agent', id: role.slug, path: `ai.iowarp.clio/agents/wtfp-${role.slug}.md`,
+    requires: [`skill:${ROLE_SKILLS[role.slug]}`]
+  });
+  for (const skill of model.catalog.skills) components.push({
+    kind: 'skill', id: skill.id, path: `skills/${skill.id}/SKILL.md`, requires: []
+  });
+  for (const id of CLIO_PLAYBOOKS) components.push({
+    kind: legacyFleetNames ? 'fleet' : 'playbook', id, path: `${playbookRoot}/${id}.md`, requires: []
+  });
+  return standardPluginManifest(model.version, 'wtfp', {
+    manifestVersion: 1,
+    // The Claude copy keeps its pre-playbook floor; Clio 0.6.1 and older reject `playbooks`.
+    compatibility: { clio: legacyFleetNames ? '>=0.4.7' : '>=0.6.2' },
+    resources: {
+      skills: 'skills', prompts: 'ai.iowarp.clio/prompts', agents: 'ai.iowarp.clio/agents',
+      [legacyFleetNames ? 'fleets' : 'playbooks']: playbookRoot
+    },
+    components
+  });
+}
+
 function clioFleetWriteBoundary(resource, fleetId) {
   if (/^project:\/\/paper(?:\/|$)/u.test(resource)) return 'paper/';
   if (/^project:\/\//u.test(resource)) return '.planning/';
@@ -1188,15 +1267,23 @@ function actionWriteRoots(action) {
   return [...roots].sort((left, right) => left.localeCompare(right));
 }
 
-// The Claude write guard arms on the manuscript-writing actions (those that
-// produce `project://paper/...`), confines Write/Edit calls for the rest of that
-// prompt to the roots the action declares, and disarms when the turn stops.
-function claudeWriteGuard(model, availabilityById) {
+// The manuscript-writing actions (those that produce `project://paper/...`)
+// available on one host, each with the project roots it declares. Both write
+// guards arm on exactly these.
+function manuscriptGuardActions(model, availabilityById, host) {
   const guarded = model.actions
     .filter((action) => availabilityById.get(action.id).available)
     .filter((action) => action.produces.some((output) => output.uri.startsWith('project://paper')))
     .map((action) => [action.id, actionWriteRoots(action)]);
-  if (guarded.length === 0) throw new Error('no manuscript-writing action is available on Claude');
+  if (guarded.length === 0) throw new Error(`no manuscript-writing action is available on ${host}`);
+  return guarded;
+}
+
+// The Claude write guard arms on the manuscript-writing actions, confines
+// Write/Edit calls for the rest of that prompt to the roots the action
+// declares, and disarms when the turn stops.
+function claudeWriteGuard(model, availabilityById) {
+  const guarded = manuscriptGuardActions(model, availabilityById, 'Claude');
   const manifest = stableJson({
     schema: 'wtfp.claude-write-guard/v1',
     actions: Object.fromEntries(guarded)
@@ -1328,6 +1415,31 @@ function geminiManifest(version) {
   });
 }
 
+// The Clio extension is installed and consented independently of the content
+// plugin. Every file its runtime reads belongs to this package; the plugin
+// link controls prompt takeover, not filesystem access to another install.
+function addClioRuntime(plan, model, availabilityById) {
+  const source = (relative) => fs.readFileSync(path.join(CLIO_RUNTIME_ROOT, relative), 'utf8');
+  const manifest = source('clio-coder-extension.yaml').replace(/^(?:#.*\n)+/, '');
+  if (!/^version: .*$/m.test(manifest)) throw new Error('clio/clio-coder-extension.yaml must declare a version line');
+  addFile(plan, 'clio-coder-extension.yaml', [
+    `# Generated by WTF-P adapter compiler v${GENERATOR_VERSION} from clio/clio-coder-extension.yaml; do not edit.`,
+    manifest.replace(/^version: .*$/m, `version: ${model.version}`)
+  ].join('\n'));
+  addFile(plan, 'runtime/extension.ts', `${generatedScriptBanner('clio', 'runtime/extension.ts')}\n${source('runtime/extension.ts')}`);
+  // `clio-coder extensions test vendors/clio-extension` runs the package tests from here.
+  addFile(plan, 'runtime/extension.test.ts', `${generatedScriptBanner('clio', 'runtime/extension.test.ts')}\n${source('runtime/extension.test.ts')}`);
+  addFile(plan, 'runtime/package.json', source('runtime/package.json'));
+  addFile(plan, 'runtime/json-schema.cjs', `${generatedScriptBanner('evaluation', 'lib/json-schema.js')}\n${fs.readFileSync(path.join(ROOT, 'evaluation', 'lib', 'json-schema.js'), 'utf8')}`);
+  addFile(plan, 'runtime/write-guard.json', stableJson({
+    schema: 'wtfp.clio-write-guard/v1',
+    actions: Object.fromEntries(manuscriptGuardActions(model, availabilityById, 'Clio'))
+  }));
+  addFile(plan, 'skins/wtfp.json', source('skins/wtfp.json'));
+  copyTree(plan, path.join(PROTOCOL_ROOT, 'project', 'schemas'), 'project/schemas');
+  copyTree(plan, path.join(PROTOCOL_ROOT, 'actions'), 'actions');
+}
+
 function makePlan(id, root) {
   return { id, root, files: new Map() };
 }
@@ -1701,6 +1813,7 @@ function addToolBundle(plan) {
     rows.push(`- \`${tool.implementation}\` → \`${outputPath}\` (legacy module \`${tool.legacyName}.js\`)`);
   }
   addFile(plan, 'tools/wtfp-tool.js', toolDispatcher(byToolId, effectsByToolId));
+  addFile(plan, 'tools/package.json', '{"type":"commonjs"}\n');
   addFile(plan, 'tools/README.md', [
     '# WTF-P bundled tools',
     '',
@@ -1723,7 +1836,7 @@ function addToolBundle(plan) {
     '',
     ...TOOL_COMMANDS.map((entry) => `- \`${entry.usage}\` → \`${entry.tool}\` (${effectsByToolId.get(entry.tool).length > 0 ? effectsByToolId.get(entry.tool).join(', ') : 'no declared effects'})`),
     '',
-    'For approved scholarly discovery, `citation-search --backend=cite-nexus --query="<topic>"` uses the separately installed `cite-nexus-wtfp` companion and its real MCP stdio server. Defaults are Crossref, DataCite and Europe PMC. Select optional vendors explicitly with `--providers`; include selected providers and query scope in the action approval. CiteNexus supports only balanced provider ordering, so omit `--intent` or use `--intent=balanced`. Results remain candidates: retain `citeNexus.sources`, field attribution, metrics, warnings and `metadata.errors`; do not infer verification or combine citation counts. The result limit is a displayed total; `metadata.total` counts the fetched deduplicated page, not the full corpus. Unavailable enrichment fails explicitly without falling back to another vendor. `WTFP_CITE_NEXUS_COMMAND` may name an absolute installed companion executable; it is operator configuration, never source content. No package is installed, server registered, or user profile changed by a tool call. Offline mode refuses this backend before process launch. Host capability blockers still apply.',
+    'For declared scholarly discovery, `citation-search --backend=cite-nexus --query="<topic>"` uses the separately installed `cite-nexus-wtfp` companion and its real MCP stdio server. Defaults are Crossref, DataCite and Europe PMC. Select providers explicitly with `--providers`. The `research-gap` full-auto route may use only free no-key public indexes (`crossref`, `datacite`, `europe_pmc`, `arxiv`) without another per-query gate; other routes require action approval naming providers and query scope. CiteNexus supports only balanced provider ordering, so omit `--intent` or use `--intent=balanced`. Results remain candidates: retain `citeNexus.sources`, field attribution, metrics, warnings and `metadata.errors`; do not infer verification or combine citation counts. The result limit is a displayed total; `metadata.total` counts the fetched deduplicated page, not the full corpus. Unavailable enrichment fails explicitly without falling back to another vendor. `WTFP_CITE_NEXUS_COMMAND` may name an absolute installed companion executable; it is operator configuration, never source content. No package is installed, server registered, or user profile changed by a tool call. Offline mode refuses this backend before process launch. Host capability blockers still apply.',
     '',
     'Every command prints one JSON document on stdout and reports failures as `{"error": "..."}` on stderr with exit status 1. Queries are capped at 512 characters, file paths at 4096, and result limits at 25. A symlinked file is accepted and read through its resolved target, which must be a regular file. Commands whose effects include `network.*` perform outbound requests to the declared scholarly indexes; pass `--offline` or set `WTFP_TOOL_OFFLINE=1` to refuse them, which is the mechanical form of "do not invoke a network-capable bibliography tool through a filesystem-only permission path". Each network command has a hard wall clock, `--timeout=<seconds>` (default 20, maximum 600); on expiry it reports `{"error": "<command> timed out after N s"}` on stderr and exits 124. `bib-impact` reports batch progress on stderr. `bib-index` flags repeated keys with `duplicate: true` and lists them under `duplicates`; `--key` refuses an ambiguous key. `bib-format` emits a standard BibTeX entry (`@article`, `@inproceedings`, ...) by default; `--style=al-folio` selects the Jekyll al-folio projection, which is not valid BibTeX. Do not execute any other module in this package directly, and do not pass a logical `project://` or `wtfp://` URI as a shell argument.',
     ''
@@ -1789,11 +1902,11 @@ function compilePlans(options = {}) {
     availabilityByTarget.set(plan.id, addActionAvailability(plan, model, plan.id, targetPolicies));
   }
 
-  for (const fleetId of ['wtfp-plan-section', 'wtfp-draft-review']) {
+  for (const fleetId of CLIO_PLAYBOOKS) {
     if (!clio.files.delete(`fleets/${fleetId}.json`)) {
       throw new Error(`cannot project missing canonical fleet for Clio: ${fleetId}`);
     }
-    addFile(clio, `fleets/${fleetId}.md`, clioFleet(fleetId));
+    addFile(clio, `playbooks/${fleetId}.md`, clioFleet(fleetId));
   }
 
   const claude = byId.get('claude');
@@ -1872,47 +1985,53 @@ function compilePlans(options = {}) {
     addFile(codex, `agents/wtfp-${role.slug}.toml`, renderCodexAgent(role, role.slug));
   }
 
-  // The canonical package. Everything Clio consumes ships here and nowhere else.
+  // The canonical content-only plugin. Its prompts also work without the desk.
   const portable = makePlan('portable-plugin', path.join(ROOT, 'vendors', 'plugin'));
   for (const [file, content] of clio.files) {
-    const native = /^(prompts|agents|fleets)\//.test(file);
-    addFile(portable, native ? `ai.iowarp.clio/${file}` : file, content);
-  }
-  const components = [];
-  for (const action of model.actions) components.push({
-    kind: 'prompt', id: action.id,
-    path: `ai.iowarp.clio/prompts/wtfp/${action.id}.md`,
-    requires: action.delegation.map(item => `agent:${item.role}`)
-  });
-  for (const role of model.roles) components.push({
-    kind: 'agent', id: role.slug, path: `ai.iowarp.clio/agents/wtfp-${role.slug}.md`,
-    requires: [`skill:${ROLE_SKILLS[role.slug]}`]
-  });
-  for (const skill of model.catalog.skills) components.push({
-    kind: 'skill', id: skill.id, path: `skills/${skill.id}/SKILL.md`, requires: []
-  });
-  for (const id of ['wtfp-plan-section', 'wtfp-draft-review']) components.push({
-    kind: 'fleet', id, path: `ai.iowarp.clio/fleets/${id}.md`, requires: []
-  });
-  const portableManifest = standardPluginManifest(model.version, 'wtfp', {
-    manifestVersion: 1,
-    compatibility: { clio: '>=0.4.7' },
-    resources: { skills: 'skills', prompts: 'ai.iowarp.clio/prompts', agents: 'ai.iowarp.clio/agents', fleets: 'ai.iowarp.clio/fleets' },
-    components
-  });
-  addFile(portable, 'plugin.json', portableManifest);
+    const native = /^(prompts|agents|playbooks)\//.test(file);
+    const actionId = /^prompts\/wtfp\/([a-z-]+)\.md$/.exec(file)?.[1];
+    const action = actionId && model.actions.find((entry) => entry.id === actionId);
+    const usesRecords = action && action.produces.some((output) =>
+      /^project:\/\/(?:manifest|config|state|decisions|structure\/outline|(?:sections|sources|evidence|checkpoints|validations)\/[^/]+)$/.test(output.uri));
+    const projected = usesRecords && availabilityByTarget.get('clio').get(actionId).available
+      ? renderMarkdownCommand(action, action.workflowBody, 'clio', availabilityByTarget.get('clio').get(actionId), true)
+      : content;
+    addFile(portable, native ? `ai.iowarp.clio/${file}` : file, projected);
+  }
+  addFile(portable, 'plugin.json', clioPluginManifest(model));
+  const availability = JSON.parse(portable.files.get('compatibility/action-availability.json'));
+  // Base bindings remain usable with the content plugin alone. The separately
+  // installed desk supplies these preferred bindings when its tools are live.
+  availability.runtimeBindings = {
+    plugin: 'wtfp', extension: 'wtfp',
+    capabilities: { 'user.interaction': 'clio:extension-interview' },
+    approvals: { explicit: 'clio:extension-interview' },
+    tools: { record: 'extension_wtfp__record', measure_section: 'extension_wtfp__measure_section', gate: 'extension_wtfp__gate' }
+  };
+  replaceFile(portable, 'compatibility/action-availability.json', stableJson(availability));
   plans.push(portable);
 
-  // Clio adopts an installed Claude plugin through the same portable root
-  // manifest, and it verifies every declared component path on disk. The
-  // Claude envelope therefore carries the identical `plugin.json` and the
-  // Clio component graph beside Claude's own `.claude-plugin/` surface. Claude
-  // Code reads neither file; its commands, agents, skills, hooks, and output
-  // style stay where its loader looks.
+  const extension = makePlan('clio-extension', path.join(ROOT, 'vendors', 'clio-extension'));
+  addClioRuntime(extension, model, availabilityByTarget.get('clio'));
+  addFile(extension, 'compatibility/action-availability.json', clio.files.get('compatibility/action-availability.json'));
+  plans.push(extension);
+
+  // The Claude envelope keeps its pre-playbook Clio namespace: a root `plugin.json`
+  // and the phase 1 prompts, agents and fleets it names, beside Claude's own
+  // `.claude-plugin/` surface. Clio no longer adopts a Claude-installed WTF-P;
+  // it labels the copy older and points to `vendors/plugin`. Claude Code reads
+  // neither file; its commands, agents, skills, hooks, and output style stay
+  // where its loader looks.
   for (const [file, content] of clio.files) {
-    if (/^(prompts|agents|fleets)\//.test(file)) addFile(claude, `ai.iowarp.clio/${file}`, content);
+    if (file === 'prompts/wtfp/help.md') {
+      addFile(claude, `ai.iowarp.clio/${file}`, clioHelpCard(model, availabilityByTarget.get('clio'), true));
+    } else if (/^(prompts|agents)\//.test(file)) {
+      addFile(claude, `ai.iowarp.clio/${file}`, content);
+    } else if (file.startsWith('playbooks/')) {
+      addFile(claude, `ai.iowarp.clio/fleets/${file.slice('playbooks/'.length)}`, content);
+    }
   }
-  addFile(claude, 'plugin.json', portableManifest);
+  addFile(claude, 'plugin.json', clioPluginManifest(model, true));
 
   const codexMarketplace = makePlan('codex-marketplace', path.join(ROOT, 'vendors', 'codex'));
   addFile(codexMarketplace, '.agents/plugins/marketplace.json', stableJson({