pplx-npx-search 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to pplx-cli will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.3] - 2026-05-26
+
+### Added
+- **Perplexity Model Council handoff.** Added `pplx council` artifact workflows plus MCP tools for creating, reading, checking, and importing Model Council review runs.
+- **Competitive-analysis template.** Added a `competitive-analysis` Perplexity Computer template that produces evidence briefs with a Council review prompt.
+
 ## [0.3.2] - 2026-05-26
 
 ### Added
@@ -73,6 +79,7 @@ First public release worth telling people about. (v0.2.0 was unpublished before
 - SSE streaming for real-time answers
 - Optional Playwright and Chrome CDP transports
 
+[0.3.3]: https://github.com/thatsrajan/pplx-cli/compare/v0.3.2...v0.3.3
 [0.3.2]: https://github.com/thatsrajan/pplx-cli/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/thatsrajan/pplx-cli/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/thatsrajan/pplx-cli/compare/v0.2.2...v0.3.0

package/README.md

@@ -102,6 +102,7 @@ pplx reason "explain the Riemann hypothesis"
 pplx research "compare React vs Vue in 2026"
 pplx labs "hello world"          # free, no auth needed
 pplx computer new "compare dinner options nearby"
+pplx council new "critique the competitive threat from Acme in enterprise search"
 pplx models                       # list available models
 ```
 
@@ -187,6 +188,7 @@ The MCP server exposes:
 - `pplx_auth_status`: validates the stored Perplexity browser cookies.
 - `pplx_models`: lists known model aliases.
 - `pplx_computer_create`, `pplx_computer_status`, `pplx_computer_read_task`, and `pplx_computer_import`: Perplexity Computer artifact handoff tools.
+- `pplx_council_create`, `pplx_council_status`, `pplx_council_read_task`, and `pplx_council_import`: Perplexity Model Council artifact handoff tools.
 
 ---
 
@@ -200,6 +202,7 @@ Query-producing commands save artifacts by default:
 - `pplx labs`
 - bare `pplx "query"`
 - `pplx computer new`
+- `pplx council new`
 
 Each run gets a folder containing `meta.json`, `query.txt`, `answer.md`, `result.json`, and `sources.json`. Use `--out <dir>` to choose the destination for one run, or set `"artifactDir"` in `~/.config/pplx/config.json` to make it persistent. Use `--artifact-id <id>` when an agent needs a deterministic run folder, and `--no-artifact` to disable saving for one search-style run.
 
@@ -220,6 +223,18 @@ pplx computer import <run-id> --out ~/Dropbox/pplx-runs --json
 
 Computer runs include `task.md`, `result.schema.json`, and `computer-result.json`. Paste `task.md` into Perplexity Computer; when the task is done, place the structured result in `computer-result.json` so local agents can read it.
 
+`pplx council` is an artifact handoff for Perplexity Model Council. It requires Model Council access in the Perplexity web UI and creates a task prompt plus result contract without claiming a private Council API:
+
+```bash
+pplx council new "critique the competitive threat from Acme in enterprise search" --out ~/Dropbox/pplx-runs
+pplx council new "review this evidence" --evidence ~/Dropbox/pplx-runs/acme/computer-result.json
+pplx council open <run-id> --copy
+pplx council status <run-id> --out ~/Dropbox/pplx-runs
+pplx council import <run-id> --out ~/Dropbox/pplx-runs --json
+```
+
+Council runs include `task.md`, `result.schema.json`, and `council-result.json`. Paste `task.md` into Perplexity Model Council; when the review is done, place the structured result in `council-result.json` so local agents can read it.
+
 ---
 
 ## Options

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pplx-npx-search",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "CLI for Perplexity AI with cookie-based auth. Headless, agent-friendly, no API key required.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -15,6 +15,7 @@ import { loadConfig } from './config.js';
 import { resolveTimeoutMs } from './timeout.js';
 import { makeArtifactContext, resolveArtifactDir, writeStandardArtifact } from './artifacts.js';
 import {
+  COMPUTER_TEMPLATES,
   createComputerRun,
   copyTextToClipboard,
   importComputerResult,
@@ -22,6 +23,14 @@ import {
   openComputerUrl,
   readTaskFile,
 } from './computer.js';
+import {
+  COUNCIL_TEMPLATES,
+  copyCouncilTaskToClipboard,
+  createCouncilRun,
+  importCouncilResult,
+  inspectCouncilRun,
+  openCouncilUrl,
+} from './council.js';
 
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 
@@ -562,7 +571,7 @@ const computer = program
 addArtifactOptions(computer
   .command('new [task]')
   .description('Create a Perplexity Computer task artifact')
-  .option('--template <name>', 'Computer task template', 'compare')
+  .option('--template <name>', `Computer task template: ${COMPUTER_TEMPLATES.join(', ')}`, 'compare')
   .option('--json', 'Output run metadata as JSON'), { allowDisable: false })
   .action(async (taskArg, opts) => {
     opts = getOpts(opts);
@@ -649,6 +658,100 @@ addArtifactOptions(computer
     }
   });
 
+// Council artifact handoff workflow
+const council = program
+  .command('council')
+  .description('Create and manage Perplexity Model Council artifact handoffs');
+
+addArtifactOptions(council
+  .command('new [task]')
+  .description('Create a Perplexity Model Council task artifact')
+  .option('--template <name>', `Council task template: ${COUNCIL_TEMPLATES.join(', ')}`, 'competitive-analysis')
+  .option('--evidence <path>', 'Optional local evidence artifact path to reference in the Council task')
+  .option('--json', 'Output run metadata as JSON'), { allowDisable: false })
+  .action(async (taskArg, opts) => {
+    opts = getOpts(opts);
+    const task = await resolveQuery(taskArg);
+    try {
+      const run = createCouncilRun({
+        task,
+        template: opts.template,
+        evidencePath: opts.evidence,
+        opts,
+        config: loadConfig(),
+      });
+      if (opts.json) {
+        console.log(JSON.stringify(run));
+        return;
+      }
+      console.log(chalk.green(`✓ Council task artifact created: ${run.artifactDir}`));
+      console.log(chalk.dim(`  Task: ${run.taskPath}`));
+      console.log(chalk.dim(`  Result: ${run.resultPath}`));
+    } catch (e) {
+      console.error(chalk.red(e.message));
+      process.exit(1);
+    }
+  });
+
+addArtifactOptions(council
+  .command('open <run>')
+  .description('Open Perplexity and optionally copy task.md for Model Council')
+  .option('--copy', 'Copy task.md to the clipboard'), { allowDisable: false })
+  .action((runId, opts) => {
+    opts = getOpts(opts);
+    const runDir = resolveRunDir(runId, opts);
+    try {
+      if (opts.copy && !copyCouncilTaskToClipboard(runDir)) {
+        console.log(chalk.yellow('Clipboard copy is only supported on macOS.'));
+      }
+      if (!openCouncilUrl()) {
+        console.log(chalk.yellow('Opening Perplexity is only supported on macOS.'));
+        console.log('https://www.perplexity.ai/');
+        return;
+      }
+      console.log(chalk.green(`✓ Opened Perplexity for ${runDir}`));
+      if (opts.copy) console.log(chalk.dim('  Copied task.md to clipboard.'));
+    } catch (e) {
+      console.error(chalk.red(e.message));
+      process.exit(1);
+    }
+  });
+
+addArtifactOptions(council
+  .command('status <run>')
+  .description('Inspect a Perplexity Model Council artifact run')
+  .option('--json', 'Output status as JSON'), { allowDisable: false })
+  .action((runId, opts) => {
+    opts = getOpts(opts);
+    const status = inspectCouncilRun(resolveRunDir(runId, opts));
+    if (opts.json) {
+      console.log(JSON.stringify(status));
+      return;
+    }
+    const label = status.status === 'complete'
+      ? chalk.green('[✓] Complete')
+      : status.status === 'pending'
+        ? chalk.yellow('[○] Pending')
+        : chalk.red(status.status === 'invalid' ? '[!] Invalid' : '[✗] Missing');
+    console.log(`${label} ${status.artifactDir}`);
+    if (status.reason) console.log(chalk.dim(`  ${status.reason}`));
+  });
+
+addArtifactOptions(council
+  .command('import <run>')
+  .description('Print a completed Perplexity Model Council result')
+  .option('--json', 'Output compact JSON'), { allowDisable: false })
+  .action((runId, opts) => {
+    opts = getOpts(opts);
+    try {
+      const result = importCouncilResult(resolveRunDir(runId, opts));
+      console.log(opts.json ? JSON.stringify(result) : JSON.stringify(result, null, 2));
+    } catch (e) {
+      console.error(chalk.red(e.message));
+      process.exit(1);
+    }
+  });
+
 // Models command
 program
   .command('models')

package/src/computer.js

@@ -10,6 +10,7 @@ import {
 
 export const COMPUTER_URL = 'https://www.perplexity.ai/computer';
 export const COMPUTER_RESULT_FILE = 'computer-result.json';
+export const COMPUTER_TEMPLATES = ['compare', 'competitive-analysis'];
 export const PENDING_COMPUTER_RESULT = {
   summary: '',
   winner: '',
@@ -18,6 +19,7 @@ export const PENDING_COMPUTER_RESULT = {
   sources: [],
   checked_at: '',
   notes: [],
+  council_review_prompt: '',
   _status: 'pending',
 };
 
@@ -34,14 +36,11 @@ const RESULT_SCHEMA = {
     sources: { type: 'array' },
     checked_at: { type: 'string' },
     notes: { type: 'array' },
+    council_review_prompt: { type: 'string' },
   },
 };
 
-export function buildComputerTask({ task, template = 'compare', resultPath }) {
-  if (template !== 'compare') {
-    throw new Error(`unsupported computer template: ${template}`);
-  }
-
+function buildCompareTask({ task, resultPath }) {
   return `# Perplexity Computer Task
 
 You are running a live comparison task for a local agent workflow.
@@ -72,6 +71,60 @@ If you cannot access the filesystem, return the JSON in the chat so the local ag
 `;
 }
 
+function buildCompetitiveAnalysisTask({ task, resultPath }) {
+  return `# Perplexity Computer Task
+
+You are running a live competitive-analysis task for a local agent workflow.
+
+## User request
+
+${task}
+
+## Instructions
+
+- Treat this as "one competitor or competitor set" plus "one topic, market, product surface, capability, pricing motion, GTM motion, or customer segment."
+- Use live web pages and direct source pages where possible, not only search snippets.
+- Check competitor-owned pages first: home page, product docs, pricing, changelog, blog, help center, release notes, status pages, public roadmaps, job postings, and app marketplace listings.
+- Add independent evidence where useful: customer reviews, forum threads, analyst commentary, news, benchmark posts, partner pages, search ads, and social posts.
+- Preserve source URLs for every material claim.
+- Separate facts from interpretation.
+- Identify:
+  - current positioning
+  - recent changes or launches
+  - pricing and packaging implications
+  - GTM and distribution signals
+  - customer pain or praise signals
+  - likely strategic intent
+  - threat level to the user request's context
+  - evidence gaps that need follow-up
+- Include the time the information was checked.
+- Mark uncertainty explicitly. Do not invent missing values.
+- Prefer structured evidence over prose.
+- Include \`council_review_prompt\`: a concise prompt that can be pasted into Perplexity Model Council to critique the evidence and strategy read.
+
+## Output target
+
+Write the final result as JSON matching \`result.schema.json\`.
+
+If you can access the local filesystem, save it here:
+
+\`${resultPath}\`
+
+If you cannot access the filesystem, return the JSON in the chat so the local agent or user can place it in that file.
+`;
+}
+
+export function buildComputerTask({ task, template = 'compare', resultPath }) {
+  if (!COMPUTER_TEMPLATES.includes(template)) {
+    throw new Error(`unsupported computer template: ${template}`);
+  }
+
+  if (template === 'competitive-analysis') {
+    return buildCompetitiveAnalysisTask({ task, resultPath });
+  }
+  return buildCompareTask({ task, resultPath });
+}
+
 export function createComputerRun({ task, template = 'compare', opts = {}, config = {} }) {
   const ctx = makeArtifactContext({ command: 'computer', query: task, opts, config });
   if (!ctx) {

package/src/council.js

@@ -0,0 +1,282 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import {
+  ARTIFACT_SCHEMA_VERSION,
+  makeArtifactContext,
+  readJsonFile,
+  writeJson,
+} from './artifacts.js';
+import { copyTextToClipboard } from './computer.js';
+
+export const COUNCIL_URL = 'https://www.perplexity.ai/';
+export const COUNCIL_RESULT_FILE = 'council-result.json';
+export const COUNCIL_TEMPLATES = ['competitive-analysis', 'strategy-review'];
+export const PENDING_COUNCIL_RESULT = {
+  summary: '',
+  consensus: [],
+  disagreements: [],
+  risks: [],
+  recommendations: [],
+  followups: [],
+  sources: [],
+  confidence: 'low',
+  checked_at: '',
+  notes: [],
+  _status: 'pending',
+};
+
+const RESULT_SCHEMA = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  title: 'pplx council review result',
+  type: 'object',
+  required: [
+    'summary',
+    'consensus',
+    'disagreements',
+    'risks',
+    'recommendations',
+    'followups',
+    'sources',
+    'confidence',
+    'checked_at',
+    'notes',
+  ],
+  properties: {
+    summary: { type: 'string' },
+    consensus: { type: 'array' },
+    disagreements: { type: 'array' },
+    risks: { type: 'array' },
+    recommendations: { type: 'array' },
+    followups: { type: 'array' },
+    sources: { type: 'array' },
+    confidence: { enum: ['low', 'medium', 'high'] },
+    checked_at: { type: 'string' },
+    notes: { type: 'array' },
+  },
+};
+
+function buildCompetitiveAnalysisCouncilTask({ task, evidencePath, resultPath }) {
+  const evidenceBlock = evidencePath
+    ? `\n## Evidence brief\n\nUse this local evidence artifact if available:\n\n\`${evidencePath}\`\n`
+    : '';
+
+  return `# Perplexity Model Council Task
+
+Use Perplexity Model Council for a multi-model review. This is a judgment and synthesis pass, not the primary web-browsing pass.
+
+## User request
+
+${task}
+${evidenceBlock}
+## Instructions
+
+- Ask the Council to evaluate the same evidence from multiple model perspectives before synthesizing.
+- Focus on the competitor, topic, market, product capability, pricing motion, GTM motion, or customer segment named in the request.
+- Separate source-backed facts from strategic interpretation.
+- Identify where the models agree and where they disagree.
+- Challenge the strongest assumption in the analysis.
+- Surface missing evidence that would change the conclusion.
+- Produce concrete recommendations and monitoring follow-ups.
+- Preserve source URLs from the evidence brief and add any new source URLs used by Council.
+- Mark uncertainty explicitly. Do not invent missing values.
+
+## Output target
+
+Return the final result as JSON matching \`result.schema.json\`.
+
+If you can access the local filesystem, save it here:
+
+\`${resultPath}\`
+
+If you cannot access the filesystem, return the JSON in the chat so the local agent or user can place it in that file.
+`;
+}
+
+function buildStrategyReviewCouncilTask({ task, evidencePath, resultPath }) {
+  const evidenceBlock = evidencePath
+    ? `\n## Evidence brief\n\nUse this local evidence artifact if available:\n\n\`${evidencePath}\`\n`
+    : '';
+
+  return `# Perplexity Model Council Task
+
+Use Perplexity Model Council for a multi-model strategy review.
+
+## User request
+
+${task}
+${evidenceBlock}
+## Instructions
+
+- Ask the Council to evaluate the request from multiple reasoning perspectives before synthesizing.
+- Identify consensus, disagreements, risks, blind spots, and decision criteria.
+- Separate source-backed facts from interpretation.
+- Challenge the strongest assumption.
+- Surface missing evidence that would change the conclusion.
+- Produce concrete recommendations and follow-up questions.
+- Preserve source URLs from the evidence brief and add any new source URLs used by Council.
+- Mark uncertainty explicitly. Do not invent missing values.
+
+## Output target
+
+Return the final result as JSON matching \`result.schema.json\`.
+
+If you can access the local filesystem, save it here:
+
+\`${resultPath}\`
+
+If you cannot access the filesystem, return the JSON in the chat so the local agent or user can place it in that file.
+`;
+}
+
+export function buildCouncilTask({
+  task,
+  template = 'competitive-analysis',
+  evidencePath,
+  resultPath,
+}) {
+  if (!COUNCIL_TEMPLATES.includes(template)) {
+    throw new Error(`unsupported council template: ${template}`);
+  }
+
+  if (template === 'strategy-review') {
+    return buildStrategyReviewCouncilTask({ task, evidencePath, resultPath });
+  }
+  return buildCompetitiveAnalysisCouncilTask({ task, evidencePath, resultPath });
+}
+
+export function createCouncilRun({
+  task,
+  template = 'competitive-analysis',
+  evidencePath,
+  opts = {},
+  config = {},
+}) {
+  const ctx = makeArtifactContext({ command: 'council', query: task, opts, config });
+  if (!ctx) {
+    throw new Error('council runs require artifacts; omit --no-artifact for this command');
+  }
+
+  mkdirSync(ctx.artifactDir, { recursive: true });
+  const createdAt = new Date().toISOString();
+  const resultPath = join(ctx.artifactDir, COUNCIL_RESULT_FILE);
+  const taskText = buildCouncilTask({ task, template, evidencePath, resultPath });
+  const meta = {
+    schemaVersion: ARTIFACT_SCHEMA_VERSION,
+    command: 'council',
+    query: task,
+    template,
+    evidencePath: evidencePath || null,
+    artifactId: ctx.artifactId,
+    artifactDir: ctx.artifactDir,
+    createdAt,
+    status: 'pending',
+  };
+  const result = {
+    query: task,
+    answer: '',
+    sources: [],
+    command: 'council',
+    mode: 'council',
+    model: 'model-council',
+    template,
+    evidencePath: evidencePath || null,
+    artifactId: ctx.artifactId,
+    artifactDir: ctx.artifactDir,
+    createdAt,
+    status: 'pending',
+    councilResultFile: COUNCIL_RESULT_FILE,
+  };
+
+  writeJson(join(ctx.artifactDir, 'meta.json'), meta);
+  writeFileSync(join(ctx.artifactDir, 'query.txt'), `${task}\n`, 'utf8');
+  writeFileSync(join(ctx.artifactDir, 'answer.md'), taskText, 'utf8');
+  writeJson(join(ctx.artifactDir, 'result.json'), result);
+  writeJson(join(ctx.artifactDir, 'sources.json'), []);
+  writeFileSync(join(ctx.artifactDir, 'task.md'), taskText, 'utf8');
+  writeJson(join(ctx.artifactDir, 'result.schema.json'), RESULT_SCHEMA);
+  writeJson(join(ctx.artifactDir, COUNCIL_RESULT_FILE), PENDING_COUNCIL_RESULT);
+
+  return {
+    artifactId: ctx.artifactId,
+    artifactDir: ctx.artifactDir,
+    taskPath: join(ctx.artifactDir, 'task.md'),
+    resultPath,
+  };
+}
+
+function assertCouncilResult(value) {
+  const missing = [
+    'summary',
+    'consensus',
+    'disagreements',
+    'risks',
+    'recommendations',
+    'followups',
+    'sources',
+    'confidence',
+    'checked_at',
+    'notes',
+  ].filter((key) => !(key in value));
+  if (missing.length) return { ok: false, reason: `missing fields: ${missing.join(', ')}` };
+  if (!['low', 'medium', 'high'].includes(value.confidence)) {
+    return { ok: false, reason: 'confidence must be low, medium, or high' };
+  }
+  for (const key of ['consensus', 'disagreements', 'risks', 'recommendations', 'followups', 'sources', 'notes']) {
+    if (!Array.isArray(value[key])) return { ok: false, reason: `${key} must be an array` };
+  }
+  return { ok: true, reason: null };
+}
+
+export function inspectCouncilRun(runDir) {
+  const artifactDir = resolve(runDir);
+  const resultPath = join(artifactDir, COUNCIL_RESULT_FILE);
+  const metaPath = join(artifactDir, 'meta.json');
+  if (!existsSync(metaPath)) {
+    return { status: 'missing', artifactDir, resultPath, reason: 'meta.json not found' };
+  }
+  if (!existsSync(resultPath)) {
+    return { status: 'pending', artifactDir, resultPath, reason: `${COUNCIL_RESULT_FILE} not found` };
+  }
+  try {
+    const result = readJsonFile(resultPath);
+    if (result._status === 'pending') {
+      return { status: 'pending', artifactDir, resultPath, reason: `${COUNCIL_RESULT_FILE} is still pending` };
+    }
+    const validation = assertCouncilResult(result);
+    return {
+      status: validation.ok ? 'complete' : 'invalid',
+      artifactDir,
+      resultPath,
+      reason: validation.reason,
+      result,
+    };
+  } catch (e) {
+    return { status: 'invalid', artifactDir, resultPath, reason: e.message };
+  }
+}
+
+export function importCouncilResult(runDir) {
+  const status = inspectCouncilRun(runDir);
+  if (status.status !== 'complete') {
+    throw new Error(`council result is ${status.status}: ${status.reason}`);
+  }
+  return status.result;
+}
+
+export function openCouncilUrl() {
+  if (process.platform === 'darwin') {
+    execFileSync('open', [COUNCIL_URL]);
+    return true;
+  }
+  return false;
+}
+
+export function copyCouncilTaskToClipboard(runDir) {
+  const taskText = readCouncilTaskFile(runDir);
+  return copyTextToClipboard(taskText);
+}
+
+export function readCouncilTaskFile(runDir) {
+  return readFileSync(join(resolve(runDir), 'task.md'), 'utf8');
+}

package/src/mcp-server.js

@@ -11,11 +11,19 @@ import { LabsClient } from './labs.js';
 import { resolveTimeoutMs } from './timeout.js';
 import { makeArtifactContext, resolveArtifactDir, writeStandardArtifact } from './artifacts.js';
 import {
+  COMPUTER_TEMPLATES,
   createComputerRun,
   importComputerResult,
   inspectComputerRun,
   readTaskFile,
 } from './computer.js';
+import {
+  COUNCIL_TEMPLATES,
+  createCouncilRun,
+  importCouncilResult,
+  inspectCouncilRun,
+  readCouncilTaskFile,
+} from './council.js';
 import { MODEL_MAP, LABS_MODELS } from './constants.js';
 
 const SERVER_NAME = 'pplx';
@@ -271,7 +279,7 @@ export function createPplxMcpServer() {
     description: 'Create a Perplexity Computer artifact handoff folder containing task.md, result.schema.json, and computer-result.json.',
     inputSchema: {
       task: z.string().min(1).describe('Live web task for Perplexity Computer.'),
-      template: z.literal('compare').optional().default('compare').describe('Computer task template.'),
+      template: z.enum(COMPUTER_TEMPLATES).optional().default('compare').describe('Computer task template.'),
       out: z.string().optional().describe('Artifact root for this run.'),
       artifactId: z.string().optional().describe('Deterministic artifact id for this run.'),
     },
@@ -290,6 +298,83 @@ export function createPplxMcpServer() {
     return toTextResult(run);
   });
 
+  server.registerTool('pplx_council_create', {
+    title: 'Create Perplexity Model Council Handoff',
+    description: 'Create a Perplexity Model Council artifact handoff folder containing task.md, result.schema.json, and council-result.json.',
+    inputSchema: {
+      task: z.string().min(1).describe('Judgment, strategy, or competitive-analysis task for Model Council.'),
+      template: z.enum(COUNCIL_TEMPLATES).optional().default('competitive-analysis').describe('Council task template.'),
+      evidencePath: z.string().optional().describe('Optional local evidence artifact path to reference in the Council task.'),
+      out: z.string().optional().describe('Artifact root for this run.'),
+      artifactId: z.string().optional().describe('Deterministic artifact id for this run.'),
+    },
+    annotations: {
+      title: 'Create Perplexity Model Council Handoff',
+      readOnlyHint: false,
+      openWorldHint: false,
+    },
+  }, async (args) => {
+    const run = createCouncilRun({
+      task: args.task,
+      template: args.template || 'competitive-analysis',
+      evidencePath: args.evidencePath,
+      opts: { out: args.out, artifactId: args.artifactId },
+      config: loadConfig(),
+    });
+    return toTextResult(run);
+  });
+
+  server.registerTool('pplx_council_status', {
+    title: 'Perplexity Model Council Status',
+    description: 'Inspect a Perplexity Model Council artifact run.',
+    inputSchema: {
+      run: z.string().min(1).describe('Run id or absolute run folder path.'),
+      out: z.string().optional().describe('Artifact root used when run is an id.'),
+    },
+    annotations: {
+      title: 'Perplexity Model Council Status',
+      readOnlyHint: true,
+      openWorldHint: false,
+    },
+  }, async (args) => {
+    const runDir = resolveRunDir(args.run, args.out, loadConfig());
+    return toTextResult(inspectCouncilRun(runDir));
+  });
+
+  server.registerTool('pplx_council_import', {
+    title: 'Import Perplexity Model Council Result',
+    description: 'Read and validate a completed council-result.json from a Perplexity Model Council artifact run.',
+    inputSchema: {
+      run: z.string().min(1).describe('Run id or absolute run folder path.'),
+      out: z.string().optional().describe('Artifact root used when run is an id.'),
+    },
+    annotations: {
+      title: 'Import Perplexity Model Council Result',
+      readOnlyHint: true,
+      openWorldHint: false,
+    },
+  }, async (args) => {
+    const runDir = resolveRunDir(args.run, args.out, loadConfig());
+    return toTextResult(importCouncilResult(runDir));
+  });
+
+  server.registerTool('pplx_council_read_task', {
+    title: 'Read Perplexity Model Council Task',
+    description: 'Read the task.md prompt from a Perplexity Model Council artifact run.',
+    inputSchema: {
+      run: z.string().min(1).describe('Run id or absolute run folder path.'),
+      out: z.string().optional().describe('Artifact root used when run is an id.'),
+    },
+    annotations: {
+      title: 'Read Perplexity Model Council Task',
+      readOnlyHint: true,
+      openWorldHint: false,
+    },
+  }, async (args) => {
+    const runDir = resolveRunDir(args.run, args.out, loadConfig());
+    return toTextResult({ runDir, task: readCouncilTaskFile(runDir) });
+  });
+
   server.registerTool('pplx_computer_status', {
     title: 'Perplexity Computer Status',
     description: 'Inspect a Perplexity Computer artifact run.',