products-mcp

This server fronts the Products pipeline — the staged system that turns a thesis and a folder of raw material into a finished two-component knowledge product. Its 26 products_* tools mirror the pipeline's shape exactly: product lifecycle, the stage dispatches (sighting, research, scope, draft), the scope-approval gates, topic and sight inspection, cover generation, section updates, job tracking, and export. The automation daemon behind it runs every dispatch as a fresh agent process and enforces the stage locks.

The tools deliberately preserve the pipeline's you-direct-every-gate model rather than shortcut it. An agent can prepare, dispatch, and monitor any stage, and it can refine a scope on your instruction — but the stages still run in order, readiness checks still apply (products_get_sight_readiness before research), and approval remains an explicit act (products_approve_scope). Working through this server from a session is equivalent to working the Products view; the same gates hold on both surfaces.

How your agents use it

• "Start a product from this seed folder." — products_create, then products_dispatch_sight to survey the material, and products_get_sight_readiness to confirm the pool is ready for research.
• "Run the next research pass on section 3." — products_dispatch_research with the section target, then products_watch_job while the researcher works; products_get_topics shows what the material actually covers.
• "Finish the package." — products_generate_cover for the cover image, products_export for the shippable bundle.

Prerequisites

The automation daemon must be running (Dashboard ▸ Platform Health). The pipeline's agent stages run on your Claude subscription; cover generation additionally uses the image daemon and your Gemini API key. Settings live in the configuration reference.

Tool reference

Tool	Parameters	What it does
products_daemon_health	—	Check the routines-daemon liveness + scheduler/sqlite/jobpool state. Call before any dispatch tool (research/draft/cover) to confirm the daemon is up. Returns {status, uptime_seconds, components, ready}.
products_list	status: string, lane: string	List products in the registry. Returns the full set unless filtered. Use this to find product_ids for downstream tools.
products_get	product_id*: string	Get full product detail: row + sections list + active claims + recent runs. The authoritative read for any product's current state.
products_create	name*: string, slug*: string, lane*: string, voice_profile*: string, target_sections: integer, images_per_section: integer, bookmark_adopted_path: string, template_source_path: string, seed_thesis: string, initial_outline: string, seed_files: array, custom_instructions: string	Stage 1 — create a new product. Three modes: Fresh (no bookmark_adopted_path, no template_source_path); Adopt (bookmark_adopted_path = existing folder under products/); Template (template_source_path = a drafted product's folder, copies its outline + drafted sections as seeds). lane='general' makes folder products/{slug}/; any other lane makes products/{lane}/{slug}/.
products_dispatch_sight	product_id*: string, custom_instructions: string, scout_timeout_seconds: integer, target_doc_paths: array, sight_batch_size: integer, sight_batch_max_kb: integer	Stage 2 Sub-flow Σ (pre-stage, added 2026-05-20) — dispatch the `product-sighter` subagent (opus). Reads the product's seed_files + seed_folders ONLY (Q13 scope) — every un-sighted-or-stale doc gets a per-doc structured sight artefact (observer-report-shaped) at `products/{slug}/sights/`. Daemon-mechanical aggregator runs at end of dispatch to build `topic_index.md` + `product_topics` DB rows. Per-product isolation enforced. Bootstrap registration step on every dispatch replaces backfill — newly-added seeds get auto-registered into `product_documents` before selection. **Prerequisite for compose dispatch (Phase 3+):** composer reads sights instead of raw seeds, so all seeds must be sighted before compose can fire. Operator triggers this from CC's SighterCard (above InitialCompositionEditor). Async — returns job_id immediately (202). Use products_watch_job to monitor.
products_dispatch_research	product_id*: string, mode: string, target_sections: integer, explicit_paths: array, seed_urls: array, source_layers: object, use_websearch: boolean, use_observer_news: boolean, use_knowledge_base: boolean, custom_instructions: string, refine_outline: boolean, targeted_section: object, target_outstanding: boolean, included_artifacts: object, clean_rebuild: boolean	Stage 2 — dispatch the product research pipeline. Three modes: • mode='compose' → product-composer reads seed_files + thesis ONLY, writes a composition .md to products/{folder}/initial_composition/. Foundation-building, accumulates, does not change status. • mode='research' → research-scout + product-researcher: writes a build-ready research .md to products/{folder}/dispatch_research/ AND maintains the unified outstanding_research.md gap-landscape sidecar at the product root. Scoped by `targeted_section` (one section), OR `target_outstanding=true` (a GAP-CLOSING run that drives the sidecar's open gaps toward zero), OR neither (general whole-outline). `targeted_section` and `target_outstanding` are MUTUALLY EXCLUSIVE. Foundation-building, does not change status. • mode='alpha' (default) → the 2-phase scope-build pipeline (2026-06-01): Phase 1 mechanically copies the canonical research note per section into scope/ + a file-scan seeds product_sections; Phase 3 product-auditor writes scope/scope_full_outline.md (overview+audit). The former LLM section-extractor (gap harvest) was RETIRED — gaps are maintained by the research subflow, not here. Transitions status research_in_progress → research_done. `alpha_phase` ∈ {all (default) | architect_only}. Async — returns job_id immediately (202). Use products_watch_job to monitor.
products_dispatch_scope	product_id*: string, mode*: string, targeted_section: object, targeted_sections: array, new_section: object, operator_prompt: string, custom_instructions: string, reference_paths: array, reference_urls: array, context_paths: array, scope_research_paths: array, section_input_path: string, gap_context: string, gap_closing: boolean, include_outline: boolean, include_outstanding: boolean, finalizer_timeout_seconds: integer, human_author_timeout_seconds: integer	Stage 3 SCOPE WORKSHOP dispatch — the per-section finalize / human-author / research / refine sub-flows + add-section + finalize-audit. Async — returns job_id (202). Costs Claude tokens (spawns an opus agent, one per section). Watch with products_watch_job. The body is full passthrough — supply the fields the chosen mode needs. Modes: • scope_research — product-researcher scoped to scope/ state + operator_prompt + reference/context files → scope/research/. targeted_section (one) OR untargeted (agent names the note). • scope_refine — product-scope-refiner per section → scope/refined/{...}_rev{N}.md. Needs targeted_section; section_input_path + scope_research_paths optional. • scope_finalize — product-section-finalizer → scope/final/{...}_final.md. targeted_section (one) OR targeted_sections (sequential batch). • scope_finalize_audit — product-auditor over the finalizer's latest-per-section set → scope/finalized_audit_outline.md (the cross-section overview the finalizer + human-author PREFER). No section payload. • scope_human_author — product-human-author per finalized section → scope/human/{section}/{...}_human.md (+ generated images). targeted_section(s) carry voice_profile/images; untargeted = every finalized section. • scope_add_section — author a NEW operator-added packaging section (e.g. a Table of Contents, a Links/Repo collection) via `new_section`. Daemon assigns the ordinal (reserved bands: beginning=min-1, end=max+1) + path; appears as a normal section.
products_approve_scope	product_id*: string, sections*: array, freeze: boolean	Stage 3 — persist the section structure (create/replace section rows). **HITL-SENSITIVE**: this is the explicit human gate in the workflow. Only invoke from agent code with explicit operator authorization in conversation. 2026-05-28 (v3): `freeze` defaults to FALSE — this is a structure-SAVE that does NOT advance status (matching the CC 'Save structure' button + the iterate-then-freeze model). Freezing now normally happens via the roll-over 'Finalize all' step. Pass freeze=true ONLY for an explicit one-shot legacy freeze (research_done → scope_frozen).
products_refine_scope	product_id*: string	Re-open a frozen scope for editing. Status flips scope_frozen/drafting/drafted → research_done. Existing drafted sections are preserved on the filesystem but the scope itself becomes editable again.
products_dispatch_draft	product_id*: string, sections_targeted: array, force_redraft: boolean, custom_instructions: string	Stage 4 — dispatch per-section drafting via the product-draft subagent. Async — returns job_id (202). Costs Claude tokens (per section). Watch with products_watch_job. Status flips scope_frozen → drafting → drafted.
products_update	product_id*: string, fields*: object	Inline field update on a product row. Supports the same allowlist as the CC inline edits: name, voice_profile, seed_thesis, initial_outline, seed_files, custom_instructions, images_per_section, target_sections, cover_image_path.
products_update_section	product_id*: string, section_id*: string, fields*: object	Inline field update on a section row. Supports target_words, title, slug, source_paths, web_urls, custom_instructions, ordinal.
products_force_unlock	product_id*: string	Operator escape hatch — release stuck SHAPE_D claims and revert status. Use when a dispatch crashed mid-flight (daemon kill, OOM, etc.) and the claim sits as 'claimed' beyond the lease. Idempotent. No body needed.
products_generate_cover	product_id*: string, aspect_ratio: string, resolution: string, style: string, custom_prompt: string, reference_images: array, overwrite_existing: boolean	Stage 4.5 — dispatch product-illustrator subagent (sonnet) → imagegen daemon → writes cover.webp to product folder. Async (returns job_id, 202). Costs Claude tokens (for prompt composition) + Gemini tokens (for image generation). Watch via products_watch_job. Cover path lands on products.cover_image_path.
products_export	product_id*: string, format: string	Stage 5 — mechanical packaging of the ship bundle. Synchronous (sub-30s typical, 'bundle' can take longer since it also compiles the human PDF). Free, deterministic. 'both' (default) = the two SHIPPED components: 'md' (agent-facing per-section .md set → dist/agentfacing/; §0 is the navigator — deliberately no consolidated file) + 'human_pdf' (human-facing orchestration manual PDF, images + cover placed, in-process Typst — no system installs). 'bundle' (added 2026-07-14) = dist/{slug}_bundle.zip — the ONE downloadable for a one-time-sale storefront: zips agentfacing/ + the human PDF + cover.webp (when present) + a bundle_manifest.json (per-file sha256/size inventory, built_at, per-component included flags). Internally (re)runs md + human_pdf with per-component partial success — a missing/ineligible human PDF still yields a bundle with whatever is available; the manifest records what's included. Legacy formats still compilable on demand: 'mdx' (consolidated, website/premium rail only) and 'pdf' (agent-facing consolidated PDF — retired deliverable). Eligibility: product status must be 'drafted' (+ human-facing rolled over for human_pdf/bundle to include it). Returns {output_paths: {md?, human_pdf?, bundle?, mdx?, pdf?}} on success.
products_watch_job	job_id*: string	Snapshot a job's output lines + running flag. Single-call only (one HTTP fetch). Agent loops this tool (with a brief sleep between calls) if it wants to wait until running=False. Returned shape: {lines: [str], running: bool, job_id: str}. Job IDs come from dispatch_research, dispatch_draft, generate_cover responses.
products_cancel_job	job_id*: string	Cancel an active job by id. Returns the cancellation status. Useful if a dispatch hangs or the operator changes their mind mid-flight. After cancel, use products_force_unlock on the product to release the claim cleanly.
products_scope_rollover	product_id*: string, target: string	Stage 3 → Draft roll-over (mechanical, no LLM). target='agent_facing' copies scope/final/*_final.md → draft/agentfacing/ (+ index.md); 'human_facing' copies each scope/human/{section}/ subfolder (the _human.md + its image_N.webp) → draft/humanfacing/{section}/ (+ index.md), SELF-CONTAINED; 'all' does both + writes scope.json + advances status → 'drafted' (fully finalized) / 'scope_frozen' (partial). 2026-06-03 — roll-over only STAGES the two self-contained draft folders; it does NOT produce MDX/PDF and does NOT set output_path (the draft section creates the PDF from draft/). The canonical Fork-A freeze step.
products_reindex_topics	product_id*: string	Re-run the mechanical topic aggregator (no LLM) → rebuilds topic_index.md + product_topics from current sight state. Returns {ok, topic_count}.
products_resight_doc	product_id*: string, doc_path*: string	Clear ONE seed doc's sight + topic rows (mechanical) so the next sight dispatch re-extracts it — re-sight a single stale/changed seed without re-sighting the whole corpus. Returns {ok, cleared, readiness}.
products_remove_seed	product_id*: string, seed_path*: string	Remove ONE seed from seed_files + soft-delete any now-orphaned registered doc. Source file on disk is NOT touched. Returns {ok, seed_files, readiness}.
products_clear_seeds	product_id*: string	Wipe the ENTIRE seed slate — hard-delete all seed docs + sights + topics + coverage and empty seed_files. Source files on disk are NOT touched. Destructive (fresh-seed-corpus intent). Returns {ok, cleared, readiness}.
products_get_sights	product_id*: string	Read the product's sights + seed_documents inventory (no cost).
products_get_sight_readiness	product_id*: string	Read sight readiness — total/sighted/unsighted/stale/unregistered + the unsighted_paths/stale_paths lists + a `ready` bool. The pre-compose/research coverage check (no cost).
products_get_topics	product_id*: string	Read the cross-doc topic index rows for the product (no cost).
products_delete	product_id*: string, confirm*: boolean	DELETE a product — removes the registry row + per-project ledger. The on-disk product folder is RETAINED. **DESTRUCTIVE + HITL**: requires confirm=true and explicit operator authorization in conversation. Returns {ok, deleted, slug}.

Where to go next

• Products — the knowledge-product pipeline — the stages, the gates, and the two-component output explained
• imagegen — the image pipeline behind covers and section illustrations