# 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](/C:/Users/Paul/OneDrive/Documents/IterFact/Codex%20Vision/README.md)

Before changing public positioning, public routes, public demos, or site copy, also read:
- [Codex Vision/27-Employment-Restriction-Guardrails.md](/C:/Users/Paul/OneDrive/Documents/IterFact/Codex%20Vision/27-Employment-Restriction-Guardrails.md)

For current MCP quality expectations and output standards, also read:
- [Codex Vision/30-MCP-Output-Quality-Spec.md](/C:/Users/Paul/OneDrive/Documents/IterFact/Codex%20Vision/30-MCP-Output-Quality-Spec.md)
- [Codex Vision/31-MCP-Coverage-and-Comparison-Spec.md](/C:/Users/Paul/OneDrive/Documents/IterFact/Codex%20Vision/31-MCP-Coverage-and-Comparison-Spec.md)

For scrape and research work, start with:
- [Webscrape/README.md](/C:/Users/Paul/OneDrive/Documents/IterFact/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:

```powershell
# 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:

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

You can also use:

```bash
iterfact mcp --host 0.0.0.0 --port 8000
```

For local development from this repo:

```bash
pip install -e .
```

PyPI release path:

- package name: `iterfact`
- publish workflow: [.github/workflows/publish-pypi.yml](/C:/Users/Paul/OneDrive/Documents/IterFact/.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
