iterfact 0.1.0

Installable CLI and MCP server for IterFact interactive documents.

IterFact Workspace

Purpose

This folder is now the Git-backed IterFact repo workspace.

IterFact is the runtime layer for AI-generated interactive artifacts.

Public-facing language can still use interactive documents as the approachable front-door phrase. But the stronger product truth is:

• AI generates an artifact
• IterFact hosts it instantly
• uploaded HTML can be hosted by trusted admins, but IterFact no longer reconstructs imported HTML into managed artifacts
• the artifact lives at a URL
• the URL embeds, shares, and distributes anywhere
• the artifact stays interactive instead of collapsing into a dead export
• saved work can now be handed directly between confirmed Iterators inside the product
• discoverable Iterator profiles are opt-in and route through trusted connection flows, not a public directory

It contains:

• the real app-plane code in apps/web
• canon docs
• MCP code
• vault assets
• prototypes and research inputs

Keep the root clean. The root should stay limited to top-level folders plus this README.

Top-level layout

• Codex Vision/ Canon markdown docs, decision log, and onboarding docs.
• Template Vault/ Saved IterFact-template-vault engines, specs, references, and builder source material.
• MCP/ Public IterFact MCP server work, deployment files, connector-specific runtime config, the current manual Railway production deploy path, and the live artifact feedback/revision loop used by Iterate links.
• Logo/ Canon brand assets and logo motion references.
• Webscrape/ Python collectors, web-scrape research, exports, and data experiments.
• Homepage Claude Prototype/ Current homepage behavior references.
• Codex Vision HTML Prototype/ Other saved HTML behavior references.
• apps/web/ The real Next.js app-plane code for iterfact.com.

Cleanliness rules

• Do not leave loose CSV exports, manifests, Python scripts, cache folders, or scrape outputs in the root.
• Put scrape and research work under Webscrape/.
• Put brand assets under Logo/.
• Put vault and engine work under Template Vault/.
• Put MCP server and connector work under MCP/.
• Put canon product, system, and workflow docs under Codex Vision/.
• Keep prototypes inside their dedicated prototype folders.
• Keep live app work inside apps/web/.
• If a new workstream starts, create a named folder for it first instead of dropping files at the top level.

Onboarding

For product and architecture onboarding, start with:

• Codex Vision/README.md

Before changing public positioning, public routes, public demos, or site copy, also read:

• Codex Vision/27-Employment-Restriction-Guardrails.md

For current MCP quality expectations and output standards, also read:

• Codex Vision/30-MCP-Output-Quality-Spec.md
• Codex Vision/31-MCP-Coverage-and-Comparison-Spec.md

For scrape and research work, start with:

• Webscrape/README.md

Working rule

GitHub should be the source of truth for live app code. This local folder is the working copy of that repo and should stay organized around:

• app code
• canon docs
• vault assets
• brand assets
• prototypes
• research and scrape work

Important deployment nuance:

• iterfact.com ships from the Vercel project iterfact-web
• that Vercel project is configured with Root Directory = apps/web
• manual Vercel production deploys should be run from the repo root, not from inside apps/web
• apps/web/.vercel/project.json can be stale local metadata and should not be treated as proof of the live production target
• verify the active web deployment with vercel inspect iterfact.com instead of assuming the most recent local Vercel deploy hit the right project
• the live MCP at mcp.iterfact.com is currently a manual Railway deploy
• pushing main alone does not ship new MCP code until the Railway deployment is explicitly triggered

Safe production commands:

# repo root
cmd /c vercel link --yes --project iterfact-web
cmd /c vercel --prod --yes
cmd /c vercel inspect iterfact.com

# repo root
cmd /c npx --yes @railway/cli deployment up -s iterfact-mcp -e production -d -m "Deploy message"
cmd /c npx --yes @railway/cli deployment list -s iterfact-mcp -e production --limit 3 --json

Current MCP behavior worth knowing:

• longform artifact creation prefers the draft flow: create_artifact_draft -> append_section -> finalize_artifact -> get_artifact_status
• failed longform finalize retries now resume from saved render checkpoints instead of restarting the full critic/render pipeline from scratch, but only when finalize_artifact(retry_failed_render=true) is used explicitly
• heavy background freeform generate_document artifacts can now resume from saved checkpoints under the same artifact_id instead of forcing a brand-new request, but retries are now explicit rather than triggered by passive status polling
• standard freeform generate_document now queues in the background by default so MCP clients do not hit the 45-second tool timeout on ordinary prompt-driven generation
• Claude-side story planning can now be handed into generate_document or create_artifact_draft as artifact_plan, so IterFact can skip the server-side planner and just render/publish the structure Claude already shaped
• generate_document and finalize_artifact now accept skip_critic=true for speed-first runs, and critic timeouts now degrade gracefully instead of blocking publication forever
• site page views and hosted artifact views can now beacon into Supabase-backed view_events, and there is now a Cloudflare/R2 sync helper for daily traffic and storage snapshots
• artifact telemetry now also splits owner vs audience views, mirrors coarse engagement into engagement_events, and supports share-level opens plus CTA/module analytics without tracking scroll depth
• live Supabase telemetry can now also be queried through /v1/telemetry/cost-audit for cost by artifact, model, step, and day
• planner and repair calls now use smart Anthropic model routing so smaller JSON-heavy jobs can downshift to Haiku automatically
• published artifact HTML is now optimized before local write or R2 upload, shrinking inline CSS/JS and markup overhead
• the MCP critic now has an agentic lane with quick checks, optional Playwright visual checks, and a production-default Claude Agent SDK backend when the Claude CLI is present; the compact Anthropic review path remains as fallback
• published artifacts opened in Iterate mode can now collect targeted notes from the live link
• those saved notes can be read back with get_artifact_feedback and applied in place with apply_artifact_feedback
• the MCP now also has a fixed regression harness in MCP/run_regression_harness.py backed by MCP/regression_cases.json
• fixed-template discovery now includes match_template, richer list_templates metadata, and a metadata-only telemetry stream summarized at /v1/telemetry/summary
• the template path is now vault-backed under Template Vault/IterFact-template-vault/templates/, with manifest-driven slot fill and primary-template plus panel composition
• templates can now declare manifest-level input contracts so some flows stay chat-friendly while finance- or model-heavy templates can require csv, xlsx, or normalized json

Current boundary worth remembering:

• uploaded HTML ingest is now effectively a passthrough-only operator path; non-admin callers should use templates or native IterFact creation instead of expecting HTML reconstruction

Python package

The IterFact MCP can now be installed as a Python package:

pip install iterfact
iterfact-mcp --host 0.0.0.0 --port 8000

You can also use:

iterfact mcp --host 0.0.0.0 --port 8000

For local development from this repo:

pip install -e .

PyPI release path:

• package name: iterfact
• publish workflow: .github/workflows/publish-pypi.yml
• release trigger: push a v* tag after the PyPI project is configured for GitHub trusted publishing

First-release requirement:

• PyPI must have a trusted publisher configured for this GitHub repo before the workflow can publish the first public release