# MomentIQ setup simplicity roadmap

MomentIQ has three audiences that need the same product explained in different ways:

1. **No-code users** who want to upload media, click a tool, preview results, and download outputs.
2. **Developers** who want an API key, SDK, docs, and copy-paste backend examples.
3. **AI-agent users** who want Claude, ChatGPT, Cursor, Replit, Lovable, or another agent to understand MomentIQ and build or run a workflow for them.

The goal is to make every path feel obvious, while giving AI agents the same setup instructions in formats they can read without guessing.

## Product rule

MomentIQ should never feel like “figure out an API from scratch.”

Every entry point should answer:

- What should I use?
- What do I give it?
- What will it return?
- How much will it cost?
- Where do I click next?
- What should I tell my AI agent?

## Final simple paths

### 1. Creator path: Moment Lab

For people who do not care about APIs.

Flow:

1. Open `https://momentiq.dev/`.
2. Choose `Use demo video` or `Upload your own`.
3. Pick one tool or a workflow preset.
4. See estimated cost based on the actual input media and selected endpoints.
5. Run the job.
6. Preview results.
7. Download clips, JSON, CSV, or timestamp tables.
8. Sign up when anonymous trial units are used.

This path should hide raw API complexity unless the user opens `View API request`.

### 2. Developer path: API and SDK

For people building a product, automation, or backend service.

Flow:

1. Click `Start here`.
2. Choose `I am building an app`.
3. Sign up or log in.
4. Create an API key.
5. Set a monthly hard spend cap.
6. Copy a Node, cURL, or Python quickstart.
7. Use the SDK to hide upload, job creation, polling, and output URL extraction.

The docs should strongly recommend server-side use only. Browser apps should call the user’s backend, not MomentIQ directly with a secret key.

### 3. AI-agent path: remote MCP and agent docs

For users who want an AI agent to help.

Flow:

1. Click `Start here`.
2. Choose `I want Claude or ChatGPT to help`.
3. Sign up or log in.
4. Create a scoped API key for the agent.
5. Set a hard spend cap.
6. Copy the MCP URL or agent prompt.
7. Give the agent the goal, the API key location, and the expected output.

Remote MCP URL:

```text
https://api.momentiq.dev/mcp
```

Fallback API URL:

```text
https://momentiq-production-7fdd.up.railway.app/mcp
```

Important: remote MCP does not mean the agent magically clicks around the MomentIQ website. It means the agent has a structured tool connection to MomentIQ actions, such as creating uploads, creating jobs, polling jobs, reading usage, and revoking keys.

Agents should be told this decision flow:

1. Check whether the agent environment supports remote MCP tools.
2. If yes, connect `https://api.momentiq.dev/mcp` with `Authorization: Bearer <MOMENTIQ_API_KEY>`.
3. If no, use the REST API or SDK from backend code.
4. If the agent cannot use tools or backend code, send the user to Moment Lab.

## AI-agent-readable surfaces

MomentIQ should expose the same setup information in multiple formats:

| Surface | URL | Purpose |
| --- | --- | --- |
| Human setup hub | `https://momentiq.dev/docs-setup.html` | Best first link for confused users. |
| Markdown setup | `https://momentiq.dev/docs/setup.md` | Copyable guide for coding agents. |
| Agent JSON | `https://momentiq.dev/ai-agent-setup.json` | Structured instructions, tools, workflows, and billing rules. |
| Plain text | `https://momentiq.dev/llms.txt` | Search/crawler/agent discovery. |
| OpenAPI | `https://momentiq.dev/openapi.json` | API shape for tool builders. |
| MCP config | `https://momentiq.dev/mcp.json` | Copyable remote MCP config. |
| Well-known MCP | `https://momentiq.dev/.well-known/mcp.json` | Discovery path for clients that look for MCP config. |
| Remote MCP guide tool | `momentiq.get_agent_guide` | Runtime guide returned directly by the MCP server. |

## What an AI agent needs to succeed

An agent needs five things:

1. **The user’s goal**
   - Example: “Find 3 funny clips from this podcast.”
2. **A media source**
   - File upload through signed upload URL, or a public/signed `media_url`.
3. **A MomentIQ credential**
   - Server-side `MOMENTIQ_API_KEY`, preferably scoped and spend-capped.
4. **A workflow choice**
   - Example: `audio/detect-energy -> audio/detect-silence -> video/clip-window`.
5. **Output expectations**
   - Preview clip, downloadable file, timestamp table, JSON proof, cost, request ID, and job ID.

If any one of these is missing, the agent should ask the user for it instead of guessing.

## Remote MCP tool plan

The remote MCP should expose tools that match real product actions:

- `momentiq.get_agent_guide`
- `momentiq.list_endpoints`
- `momentiq.get_endpoint_schema`
- `momentiq.estimate_cost`
- `momentiq.list_workflows`
- `momentiq.plan_integration`
- `momentiq.get_code_example`
- `momentiq.run_agent_diagnostics`
- `momentiq.check_job_readiness`
- `momentiq.create_workflow_job`
- `momentiq.continue_workflow_job`
- `momentiq.create_upload`
- `momentiq.create_job`
- `momentiq.get_job`
- `momentiq.get_job_result`
- `momentiq.list_jobs`
- `momentiq.get_usage_summary`
- `momentiq.list_api_keys`
- `momentiq.create_api_key`
- `momentiq.revoke_api_key`
- `momentiq.get_account_limits`
- `momentiq.set_spend_cap`
- `momentiq.create_billing_link`
- `momentiq.regenerate_output_url`

## Payment and abuse rules for agents

AI agents should be powerful, but not unlimited.

Rules:

- Agents use the same API keys as developers.
- Usage consumes free credits first.
- After credits are gone, billing must be active.
- Failed jobs are not billed.
- Keys can be scoped by environment and endpoint group.
- Users should set a hard spend cap before giving a key to an agent.
- Revoked keys must stop working immediately.
- The agent should never receive an unrestricted admin key.

## Website clarity fixes

Every page except dashboard pages should have one primary account action:

```text
Sign up / Log in
No subscription. Usage-based. $5 credit to start.
```

Avoid competing top-level CTAs like:

- `Get API key`
- `Sign in`
- `Start free`
- `Create key`
- `Quickstart`

Instead, route all account entry to the dashboard auth flow, then show the correct next step inside the dashboard.

## Dashboard clarity fixes

Dashboard should be action-based, not decorative.

Required areas:

- Account status
- Free credits remaining
- Billing status
- Usage this month
- Hard spend cap
- Usage alerts
- API keys with create/revoke/copy-once behavior
- Jobs and failures
- Usage by endpoint
- Usage by API key
- Billing portal
- Settings that actually save and propagate

Avoid duplicate controls:

- API key creation belongs mainly on API Keys.
- Billing setup belongs mainly on Billing.
- Spend cap and alerts belong mainly on Settings, with read-only summary cards elsewhere.

## Phase roadmap

### Phase 1: Explain the paths everywhere

Status: mostly implemented.

Tasks:

- Add `Start here` to nav.
- Add setup hub page.
- Add `docs/setup.md`.
- Add `llms.txt`.
- Add `ai-agent-setup.json`.
- Add OpenAPI starter spec.
- Add MCP config files.
- Link the setup hub from homepage, docs, and agent docs.

### Phase 2: Make examples copy-paste ready

Tasks:

- Add a dedicated `docs/agent-examples.md`.
- Include Node SDK examples for local file upload and job polling.
- Include cURL examples for presign upload, PUT, job creation, and polling.
- Include prompts for Claude, ChatGPT, Cursor, Replit, and Lovable.
- Include the safe first endpoints.
- Include “what not to do” examples, especially exposing API keys in browser code.

### Phase 3: Make Moment Lab truly no-code

Tasks:

- Clear `Use demo video` and `Upload your own` buttons.
- Highlight the active media source.
- Compute price from real input media and selected endpoint chain.
- Let users chain endpoints visually.
- Hide raw JSON behind a toggle.
- Show result preview only after output exists.
- Add download buttons for generated clips/tables.
- Require signup only after trial units are exhausted.

### Phase 4: Make SDK usage boringly easy

Tasks:

- Publish or package the Node SDK.
- Add `clipWindow({ file, start, end })`.
- Add `detectEnergy({ file })`.
- Add automatic signed upload.
- Add automatic job creation and polling.
- Add `resultUrl` extraction.
- Add retry/backoff and useful errors.

### Phase 5: Expand remote MCP

Tasks:

- Add cost estimation tool.
- Add endpoint schema/detail tool.
- Add workflow listing tool.
- Add integration planning tool for vague user goals and app-builder prompts.
- Add code example tool for Node, Python, and curl upload/job/polling flows.
- Add agent diagnostics tool for worker/storage/billing/free-credit/spend-cap readiness.
- Add job readiness validation tool.
- Add workflow job creation tool.
- Add workflow continuation tool for chaining one completed job into the next safe step.
- Add spend cap read/update tool.
- Add output URL regeneration tool.
- Add a public unauthenticated discovery endpoint for tools and docs.
- Add copy-paste remote MCP setup snippets for Claude, Cursor, Replit, Lovable, and ChatGPT.
- Add a beta agent smoke-test checklist for key setup, spend caps, MCP connection, upload, workflow, usage review, and key revocation.

Status: current MCP tool coverage is implemented for discovery, endpoint schema lookup, integration planning, code examples, agent diagnostics, uploads, job readiness checks, jobs, workflow planning, workflow continuation, spend caps, billing links, API key management, usage summaries, and output URL regeneration. The AI agent setup page now includes copy-paste remote MCP setup snippets for Claude, Cursor, Replit, Lovable, and ChatGPT plus a beta smoke-test checklist. Future MCP work should now prioritize real beta user friction.

### Phase 6: Beta launch hardening

Tasks:

- Confirm live endpoints are reliable on Railway workers.
- Confirm R2 upload/download works from browser.
- Confirm signed output URLs can be regenerated.
- Confirm Stripe live billing and webhooks.
- Confirm usage records and free credits are accurate.
- Confirm revoked keys stop immediately.
- Confirm spend caps block before overage.
- Confirm dashboard data is real, not hardcoded.

## First live-safe endpoints

Sell these first:

- `video/clip-window`
- `video/clip-near`
- `audio/detect-silence`
- `audio/detect-energy`

Mark the rest as preview until they are tested end-to-end with production workers:

- `audio/detect-laughter`
- `audio/detect-speakers`
- `audio/detect-music`
- `audio/isolate-speech`
- `audio/find-words`
- `audio/topic-segments`
- `video/best-frames`
- `video/best-frame-near`
- `video/text-frames`
- `video/detect-cuts`
- `video/dedupe-frames`
- `video/thumbnail-score`
- timeline workflow endpoints

## Success criteria

MomentIQ is simple enough when:

- A creator can upload a video and download a clip without reading docs.
- A developer can run a real job from copied SDK code in under 10 minutes.
- An AI agent can read `llms.txt`, `ai-agent-setup.json`, OpenAPI, or MCP guide and know how to proceed.
- A user can safely give an agent a scoped key with a spend cap.
- Billing and usage are understandable before a job runs.
- Every failed job shows a useful error, request ID, and job ID.